


LOGIC PROGRAMMING ASSOCIATES LIMITED (LPA) - 


END-USER LICENSING AGREEMENT 


You {the Purchaser) have acquired a Package comprising Software and Documentation. By opening 
the disk enclosure you have agreed to abide by the terms of this Agreement, which are:- 


1. Copyright 

All copyright title and intellectual property rights 
in the Package are retained by LPA. LPA grants 
you a non-exclusive licence to use the package 
on a single machine only. You may make copies 
in any machine-readable or printed form for back- 


‘up or modification purposes in support of your 
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own use on a single machine only (except insofar 
as any software is copy-protected) and to every 
copy or modification you must attach a 
permanent label giving the name of the Software 
and stating that it is the copyright of LPA. You 
may not copy the printed Documentation. 


2, Multi-Computer Use 
If you wish to use the Package on more than one 
machine you must inform LPA and pay a further 
licence fee depending on the number of 
computers to be used. 


3. Transfer 

You may transfer the Package and this single 
computer licence to another person if, and only if, 
(a. that persor agrees to accept the terms and 
conditions of tnis agreement and (b) you transfer 
the whole of the Package and all copies and 
modifications ‘unless you destroy any copies and 
modifications which you retain} and {c) the 
copyright notice is attached to every copy and 
modification and (d) both you and the transferee 
sign and return the re-registration form and 
agreement contained in the reference manual. 
You may not transfer a multi-computer licence. 
Unless all of these conditions are fulfilled you 
may not transfer the whole or any part of this 
package or this licence to any other person. If 
you try to do so then your own licence is 
automatically terminated. 


4, Updates 

If you have completed the Registration Card (or, 
in the case of the Assignee, the re-registration 
card) and returned it to LPA, LPA may (but shall 
not be obliged to) sell you any update to the 
Package and this agreement shall apply also to 
any update and to any replacement disk. Please 
note that any offers which LPA may make of 


updates at special rates are available only to the . 
Registered Owner. It is therefore in your own 
interests to ensure that you are registered. 


5. Limited Warranty 

LPA warrants only that the disk on which the 
software is provided is free from defects in 
materials and workmanship under norma! use for 
30 days from your receipt of it. LPA does not 
make any representation warranty or guarantee 
that the Package is fit for any particular purpose. 
lf you return the Package and your receipt to LPA 
and can demonstrate to LPA that the disk has not 
been misused or used on defective or. 
incompatible equipment but is nonetheiess faulty 
then LPA will supply a replacement free of 
charge. Thereafter, if you have registered with 
LPA in accordance with paragraph 3 acove LPA 
will, upon receipt by LPA of the original disk and 
LPA's current replacement fee, replace any copy- 
protected disk which has been corrupted. This is 
LPA's entire liability and your sole remeay. In no 
event shall LPA be liable for any direct or 
consequential loss of any kind, except that which _ 
is unlawful to exclude. If any such exciusion of | 
liability shall be held to be unlawful for any 
reason then LPA‘s liability shall be limited to the 
one-time licence fee paid to LPA by the end-user 
upon the grant of this Licensing Agreement. 


6. Term 

You may terminate this Agreement at any time. 
LPA may terminate this Agreement if you are in 
breach of any of your obligations uncer this” 
Agreement or if you become insolvent. Upon 
termination for any reason you undertake 
immediately to destroy the Package and any copy 
modification or merged portion in any form. 


7. English Law 

Unless you are resident in the United States of 
America (in which case this Agreement shall be 
governed by the law of the State of California) 
this Agreement is governed by English Law and 
the English Courts shall have sole jurisdiction in 
any dispute. 


This is the complete statement of the entire terms of the Agreement between you and LPA. You 
acknowledge that you have read it and understood it and, that by opening the Package or permitting 
the Dealer to open it for you, you agree to be bound by its terms. 
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Introduction to LPA MacPROLOG 


LPA MacPROLOG represents the successful combination of a state of the art Artificial 
Intelligence language and the user-friendly interface and enhanced graphics of the Apple 
Macintosh. By integrating PROLOG with the Macintosh philosophy of mice, menus 
and icons, and by implementing a true multi-window management system, LPA has 
provided PROLOG programmers with a sophisticated and rich programming 
development environment, previously unavailabie on micro-computers. 


LPA MacPROLOG uses an extension of the industry standard Edinburgh PROLOG 
syntax and an extended set of VO and PROLOG data base primiuves that greatly enhance 
its power as an AI language. The subset of LPA MacPROLOG comprising standard 
PROLOG primitives is compatible with Quintus PROLOG. In addition to these 
PROLOG orientated primitives, LPA MacPROLOG also provides a comprehensive set 
of primitives specific to the Macintosh environment of windows. menus, dialogues and 
graphics. 


By virtue of its fast incremental compiler, LPA ..facPROLOG <.aims not only to be the 
most advanced PROLOG system available on any micro. but also a powerful, 
general-purpose, high-level Macintosh application language which enables the rapid 
prototyping of Macintosh applications. 


With its powerful optimising compiler and efficient implementation, LPA MacPROLOG 

also provides the basis for quick final applications. An example of this is the LPA 

MacPROLOG programming environment itse!f. which at neariv 400K of compiled 
PROLOG, is itself a testimony to the speed and power of the unceriying language design 
and implementation. 


In line with LPA’s philosophy of high-level and ceclarative systems. LPA MacPROLOG 
provides access to the Macintosh Toolbox and QuickDraw routines in a simple but 
efficient manner and removes a lot of the pain of programming the Macintosh irom the 
programmer. For example, there are powerful primitives to generate dialogues. instail 
user menus, track the mouse, or draw and manipulate complex sraphical objec:s. 


There is a comprehensive range of pre-defined dialogues but in addition users can 
implement their own bespoke dialogues by describing the configuration of Suttons, 
check boxes, edit fields, scrolling menus, icons. text and pictures by a list of terms. A 
single call then displays and reads from the dialogue. For the adventurous there are 
extended ‘dynamic’ dialogues where the dialogue configuration can be manipulated 
under the control of a running PROLOG program. 


Menus can be simply installed, extended, removed or altered with a single call to a 
primitive. User selections on a menu automatically invoke the PROLOG programs 
associated with that menu item. 


All the window handling routines used in the LPA MacPROLOG development 
environment are available to the programmer as primitives of the language. Windows can 
be created, displayed, hidden, moved. killed, or used as I/O channels through program 
calls. This allows applications to make full use of the multi-window management 
system of LPA MacPROLOG and also all the standard Macintosh facilities such as the 
clipboard and desk accessories. 


A recent feature of LPA AfacPROLOG is its unique high-level graphics system. where 
graphical objects are defined in a declarative and descriptive manner. This powerful 
combination of graphics and PROLOG 2ppears within the programming environment in 
the shape of a call-graph option which enables users to graphicaliy display and interact 
with programs. This concept of graphical debugging tools is one that LPA hopes to 
develop and expand on in the near fetere in line with users’ wishes for a simpler and 
faster wav of maintaining and refining programs. 


Graphical applications are easily implemented by defining graphical tool programs which 
are then invoked when the user clicks on that tool's picture. 


By combining LPA MacPROLOG’s window, menu, dialogue and graphics handling 
primitives, programmers can now develop serious complex applications and provide a 
simpie and attractive user interface. 


The latest addition to LPA MacPROLOG is an interface to both C and Pascal. This 
allows programmers to use code alrezcy developed and established in these languages 
from within PROLOG. 


Future LPA plans include the implementation of colour, a database interface toolkit, and 
an exper system toolkit 


LPA MacPROLOG is the product of 8 years of LPA experience in the design and 
implementation of PROLOG systems. We trust you will find our time and effort 
worthwhile, and we are always happy to receive any comments you may have on LPA 
MacPROLOG, and news of how youre using it. 
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Find top picture under mouse 
Repiace top picture under mouse 
Find list of pictures under mouse 
Find pictures in rectangle 
Test if point is in picture 
Dr2g graphic rubber band 
Dreg pictures 
Wait for mouse click 
Test if mouse click has occurred 
Get mouse position 
Test 1f mouse 1s depressed 
Test if mouse released 
Set up graphic text edit rectang‘e 
Set up graphic text edit line 
Get text from edit field 
Get current text font details 
et current text font details 
Get font details 
Get width of atom in a font 
Inset a rectangle 
Offset a rectangle 
Intersection of two rectangles 
Union of two rectangles 
Test if point is in rectangle 
Test if rectangle is in rectangle 


320 


322 
324 
324 
325 


326 
326 
327 
327 
329 
330 
330 
332 
333 
334 


Cae 
Coe 
tai 
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1 Edinburgh Syntax 


The Edinburgh syntax of LPA MacPROLOG™ is essentially the syntax of the book 


Programming in Prolog 
by Clocksin & Mellish 
published by Springer-Verlag 


It is the syntax which originated with the Edinburgh University DEC-10 compiler, hence its name. 


In this Chapter we briefly summarise Edinburgh syntax. Those familiar with the syntax should pay 
special attention to sections 1.6 and 1.13, which describe some special features of MacPROLOG 
Edinburgh syntax. 


Edinburgh terms 


There are six types of Edinburgh term: numbers, atoms, variable names, lists. Strings anc 
compound terms. 

Variable names and atoms are disjoint. A distinction is made between variable names anc 
variables. Vanable names are converted into variabies when clauses are used or when terms ure 
read in using the normal read primitive for Edinburga terms. However, there are input primitives 
such as greaz and prompt _aread that read in Ecinburgh terms without converting variable 
names into variables. They will be left in the term as (quoted) atoms. These primitives also retum 
the list of varigdie names in the read-in term as the value of an extra argument varladi2 ci the ciui 


1.1 Character set 


\JacPROLOG uses the 8-bit ASCII character set , inciuding all the the special churacters woove 
ASCII 128 provided on the Mac. The characters are represented internuily by 8-bit numoers (BVIeS: 
in the range 0.255. 

(See the Aprendices for the Macintosh character set.) 


1.2 Separators and terminators 


The normal term separator is the comma. This is used to separate terms in lists. 

The full stop followed by a space or a carriage return is the normal term terminator. aithough in 
dialogue ecit fields the terminating full stop is optionai. If a full stop is not followed Dy a space or 
carriage return it is interpreted as a symbolic atom. 

A space between an atom and a left round bracket ( 1s also significant. 

A space must also be used to separate an operator from an operand if they are the same token type. 
e.g. both alphanumeric tokens. 


1.3 Comments 


A comment can be inserted at any point in an Edinburgh program window. It is any sequence of 
characters that begins with /* and ends with */. 


End of line comments (a sequence of characters started by a % character and continuing until the end 
of the line) are also supported. 
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1.4 Numbers 


Numbers are either integers or floating-point numbers. An integer is any number with no 
fractional part. 


A positive integer is written as a contiguous sequence of digit characters, with no leading sier 
character. A negative integer is a sign character (-) contiguously followed by a positive integer. A 
sign character not directly followed by a positive integer is not regarded as the sim of a number. 
Integers are stored as signed 24 bit numbers in MacPROLOG. The following are integers: 


9821 211327 —S2 768 0 
Floating point numbers are written in fairly conventional notation. as illustrated below: 
2e3% 10.3eS5 22 .0038=100 Suap 


One and only one period must be present in a floating point number. and it must be 
contiguovsly followed by a digi. As with an integer, a floating point number must start with 2 
digit or & minus sign and a cigit. It canno: start with a period. The e exponent is optional, but: 
usec it must be contiguous to the number and must be contiguously followed by an integer. 
Tne folowing are not floztng point numbers: 


t 


9 /* starts with . */ 
3e~-22 noL" 
24 e3 /* space before e*/ 
-.7e45 /* no digit after -* / 
5624.8 /* exponent not an integer */ 


/* no digit after . */ 


Floating point numbers may be written in fixed point notation (e.g. 123.42) or scientific 
notation (e.g. 1.234552). MacPROLOG will print numbers in the scientific notation if thes 
cannot be printed in fixed point format (i.e. they are either too large or too small). This means in 
practice that all numbers with magnitudes between 1 and 99,999,999 inclusive are displaved 
without exponent, and any numbers with magnitude between 0.0000001 and 0.9999999 are 
displayed without exponent, provided that there are no digits after the 7th decimal place. 


Thus 12345.678 is displayed as 12345.678 

and 12345678 is displayed as 12345678 

but 123456789 is displayed as 1.2345678E8 
also 1.234567E-1 is displayed as 0.1224567 

but 1.2345678E-1 is displayed as 1.2345678E-1. 


Numbers have up to 8 digits of precision, and have an exponent in the range -127 to 127. 


As with integers, negative floating point numbers have a sign character in front of them, and 
positive floating point numbers do not have a sign character. If you enter 


+6.86 
this will be interpreted as the operator + applied to the positive number 6.86. 
Note that MacPROLOG allows the free mixing of integers and floating point numbers. The 


anthmetic primitives automatically convert integers to floating point numbers where necessary; but 
there are also special primitives for integer only arithmetic. 
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1.5 Atoms 
Atoms are of three types: alphanumeric, symbolic and quoted. 
An alphanumeric atom is a lowercase letter (a-z) followed by a sequence of zero or more 
alphabetic characters or digits. The underscore character _ counts as an alphabetic character. The 
hyphen character - does not. Example: 

apple h4é- apple cart 


are three alphanumeric atoms. 


A symbolic atom is a contiguous sequence of symbolic characters suchas *, > OF A. However 
the eleven symbols 


ey A ££ ae we SY hs 
cannot appear in a symbolic atom since they have a special syntactic roie. 
The full stop can appear in a symbolic atom, but remember that fuil stop followed by a space or 
carriage return is the term terminator. 
For example: 
&&/ << safo i a fs 
are five symbolic atoms. 
(Notice that the /* appezring in *>/* is part of the symbolic atom, and in this case is not 


interpreted as the start of a comment.) 


A quoted atom is any sequence of characters surrounded by single quotes. 
For example: 


‘Rople' the green **** Annt 
are three quoted atoms. 
The single quote character can be represented by two adjacent single quote characters. 
To insert control codes use ~/etter where control-/erter is the contro! code. 
For example, to insert the carriage return control character in a string. which is control-M (ASCII 


13) use the pair of characters ~M. The tilde, ~, is an escape character. To insert a ulde use ~~. 


The maximum size of an atom is 255 characters (in the unquoted name). 
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1.6 Variable names 


Variable names are alphanumeric sequences of characters beginning with an upper case letter (A-2) 
or an underscore . 


Apple 23 X 
are three variable names. Quoting with singie quotes over-rides the variable name convention. 
"Apple" PRI 
are both quoted atoms. 
An underscore on its own is an anonymous variable. Different occurrences of the _ anonymous 
variable in a read-in term are mapped into c:fferent new variable names of the form on where = 
is an integer. These names begin with a couble underscore. To avoid a possible ciash of names 


vou should not use double underscore variable names of this form in a term in which there are 
anonymous variables, 


WARNING 


in MacPROLOG, you cannot use quotes io over-ride the variable name convention if the quotes 
atom is also used unquoted in the same tem as a variabie name. For example, in the list 


eae EEE] 


oniy the 'z' will be an atom. Both the cuoted and unquoted occurrences of X will be interpreted 
as occurrences of the same variable name °:. 


:.7 Compound terms 


A compound term is an atom or vari2>.2 name immediately followed by a sequence of k terms 
enclosed in round brackets and separated one from the other by commas. It is of the form 


£(tz,to,.-,ty,) k2]1 


The f is the functor. The term t; isthe i'th argument. k is the arity. 


When a variable name is used it is usualiy when the term is a condition of a clause and the vanabie 
name is a meta-variable standing for a precicate name. See the section on meta-variables below. 


>(2,3) likes(tom,méry) read (Z) 


are three compound terms. 
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1.8 Lists 


Lists are sequences of terms separated by commas and surrounded by square brackets. They are g! 
the form: 


Corner TA k20 


When k=0 we have the empty list [}. 
Example: 
{23,apples, {X,7]}] 


is a list of three items, with its third element also a list. 


1.8.1 List patterns 


The form 
(to,to,-..t, iVariable; i21 


is the pattern of a list that begins with the i terms =-,*>,..0; followed by some remain:c z 
list of terms represented by the Variatie. 


An alternative to | is the sequence , .. (a comma followed by two full stops). So the upc.2 
pattern can be wniten 


ion, E pret - PE Variable) i>} 


1.9 Strings 
A string is a sequence of characters surrounded by couble quote characters. Itis an sbdrevintec 


notation for the list of decimal integer ASCII codes of the characters in the sequence. 
For example. 


hoy“ 
is shorthand for the list of five integers 
(65,32; 96; 2225121] 


To insert the double quote character, use two adjacent double quote characters "". 

To insert control codes use ~/etrer where control-/erter is the control code. 

For example, to insert the carriage return control character in a string. which is control-M (ASC. 
13) use the pair of characters ~M. The tilde, ~, is an escape character. To insert a ulde use ~~. 
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1.10 Operators 

As an alternative to the prefix form, compound terms of the form 
Tt] 

with arity 1 can be written in the alternative operator expression form 
Ye 

providing f has been declared a prefix operator, or the operator expression form 
Cr 

providing £ has been declared a posix operator. Compound terms of the form 
g(t ,,C 2) 

of arity 2 can be wntten in the alternative operator expression form 
BL k2 

providing g has been declared an infix operator. 


The declaration of an operator is achieved either by using the Operators... meru command o7 
by using the cp primitive (the operator Cec.aration may be included in the '<LOZ=2>' program ci 
an application - see the chapter on Implementing an Application). 

An operator declaration is a term of the form 


Co (priority, =e; co sams) 


where pricrity isan integer between i and 1200, cc name is the operator name and tyre 
is one of: 


= for non-associative prefix operator 
fy for right associative prefix operator . 
xe for non-associative postfix operator 
ve for left associative postfix operator 
REX for non-associauve infix operator 
“ty for nght associative infix operator 
JEX for left associative infix operator 


When several operators have the same ceciaration, the op name argument of the co declaration 
can be a list of operator names. 


The priority determines the binding of an operator to its arguments when the argument of an 
operator is itself an operator expression. The lower the priority number, the more binding the 
operator. i 
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AS an example 
2% i ES 
is the compound term 
TA 124 0) pO) 
because * is a predeclared operator with priority 400 anc ~ is predeclared with priority 500. 
An operator name can be declared with more than one 7.76. 
Brackets can be used to over-ride the priorities. For exampie, 
27 1248) 
is the compound term 
712,+(35,8)) 


The following are the predeclared operators of MacPRC_OG Edinburgh syntax: 


Priority Type Name Priority Type Name 
12609 xfx :- 500 yix 
1200 xfx <--> 500  yfx 
1200 fx :- 500 fx - 
1200 fx ?- 500 fx - 
1150 fx moce 500 fx 
1O fs püsi 

1100 xf ? 

1100 xfy ; 400 yfx >”? 
1100 xfy | 400 vix * 
1050 xfy -> 400 yfx 
1000 xfy , 400 yfx 
900 fy net 400 yfx « 
900 fy spy 400 yfx » 
900 fy nospy 400 yfx << 
700 xfx = 400 yiz >> 
700 xfx \= 300 xox Sea 
700 xfx is 200 xiv ° 
700 xfx =.. 

700 xfx \== 

700 xÍx =:= 

700 xfx =\= 

700 xfx < 

700 xfx > 

700 xfx =< 

700 xfx >= 

700 xfx 2 

700 xfx < 

500 yfx + 

500 3 yfx ++ 

500 yfx - 

500 yfx -- 
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1.11 Call Terms 


A call term is an atom or 2 compound term that does not have : ~ as its functor. 
Examples: 


rue 


rs .— t 


(COR; A) 


kes 
pend([j; X.X) 


ai 
ap 


((iikes (x; Yl; male (Yj) is a conjunctive call term. 


1.12 Clauses 
A clause is acall term which is either an unconditional clause, or a term of the form: 
Ci 704,02... Fi >} 


where t isa call term (the nead of the clause) and each z; isa variable name or a altern (ie 
conditions ct the clause}. 


A clause is the compound tem 
eeta yp Cte e (bgp a tgergir) 


where :- ang ', ' are functors. Notice the necessary quoting of the comma. t 1s the head of the 
Clause -and cartonato Ts tne body. The functor of = (or the name if it is an atom) ìs the 


relation that the clause is a@npout!. 


Exampies: 


af 
eet? List, !EdiATl]): -acpend(T.,i1ist,ATl). 
Lives {tør 2-a0rse (2) ,52ack (X) 


The first two are clauses about append, and the third a clause about Likes. MacPROLOG does 
not distinguish between diferent uses of the same relation name with different arities. 
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1.13 Meta-variables 


There are two forms of meta-variable allowed in MacPROLOG: predicate symbol meta-variable 
and condition meta-variable. 


If a body condition of a clause is a compound term with a variable name as the functor, i.e. if it is a 
condition of the form 


Varname (C4558) 


then Varname is a predicate meta-variable. The meta-variable must be bound to an atom which is 
the name of a defined relation by the time that the conc:tion 1s evaluated, otherwise an error occurs. 


For example, the following defines a mar relation: 


map(R,[],{1). 
map(R, [UIL]; [(MUIMLj}:- | 
1 
map (L, ML) . 


If a body condition of a clause is a vanable name. this is a condition meta-variabie. It must be 
bound to aterm that represents a call by the time that it is evaluated. This term can be 


(1) an atom, a cali toa no argument relation 
2} a compound term of the form 


relation_name(t4,tp,.-.tp) 
or (3) a list of the form 


[relation_name,tj,ty..ty] 


Both (2) and (3) represent calls to the program for relaticn_name with arguments 
c] , Cal p 

(1) and (2) are normal call terms . 

(3) is an additional way of representing a call which is allowed as the value of the cai! 


meta-variable. 
For example. the following is the definition of the nc= primitive: 


not (C):— C,!,fail. 
noc (C7 4 


not can be called with an atom, a compound term or a list as argument. 
These meta-variable facilities are somewhat more powerful than those usually allowed in Edinburgh 


syntax. Usually only the condition meta-vanable is allowed, and that variable cannot be bound to a 
list to represent the call. 
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1.14 Definite Clause Grammars 


Definite clause grammars allow the programmer to build programs which are intended for parsin £ 
applications, for example natural language parsers and programming language compilers. DCG 
Tules are automatically converted into normal Prolog clauses which are then compiled in the usual 
way. In effect the DCG formalism is an extra Syntactic layer on top of regular Prolog. The 
mechanism used to implement DCGs can also be used to provide alternative syntactic layers, for 


example the programmer may wish to have a macro facility, in which case this would be 
implemented in the same style as DCGs 


A DCG rule looks like a normal Prolog clause, but it has the particular form: 
nead --> bod:. 


Tne meaning of this rule is that input which matches body can be reduced to head. or alternatively 
when using this rule in the conventione) Prolog top-down Style, “in order to recognise a head 
recognise a body”. 


The body is a sequence of terminals, non-terminals and conditions separated by commas. A 
terminal symbol is a literal which must appear in the input and is represented by a String or a list. 
For example if we were constructing an arithmetic expression parser we might have a rule which 
identified arithmetic operators: 


add Op ==> "=". 
add op -e> Mat 
loop --> [42). 


ASCII code for * is 42 


BEZZF code for / is 47 


oC no 


^ non-terminal takes the form of a normal compound term which may optionally include 
arguments. Arguments in non-terminals are useful to return the ‘result’ of the parse. 
For example, when parsing an expression we might want the expression tree as the answer: 


acd _exp(Lefi+Right) --> add_exp(Left),"+",add_exp(Right). 
add exp (Left-Kight) ==> add exp (Left), "=<",add. exp (Richt) . 
mul exp (Left*Right) --> mul_exp(Left),"*",mul_exp (Right). 
mul exp (Left/Right) ~-> mul _exp(Left),"/",mul_ exp (Right). 


A more succinct way of writing this grammar would make use of variable functors: 
add_op(+) --> "+". 
add- opie) =<2 Tem 
mul op(*) --> [42]. 
mul_op(/) --> [47]. 


add_exp(Op(L,R)) --> add_exp(L),add_op(Op),add_exp(R). 
mul_exp(Op(L,R)) --> mul_exp(L),mul_op(Op),mul_exp(R). 
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There can be any number of rules for each definition of a non-terminal. The full arithmetic 
expression must allow both additive and multiplicative operators: 


exp(E) --> add_exp(E). 
exp(E) --> mul exp (E). 


Bodies of rules may also contain alternatives. These express altemative ways of obtaining a parse. 
Our two rules for exp can be expressed in the single rule: 


exp(E) --> add exp(E) | mul_ezz (E). 
Apart from terminal symbols and non-terminals a body of a DCG rule can contain conditions. 


Conditions are normal Prolog calls which are used to provide context sensitive tests 2::though in fact 
any normal Prolog call can be used as a condition. 


In our arithmetic expression parser we allow for arithmetic operators. but we musi aiso allow for 
integers. We could write the rules for integers as a sequence of rules ixe: 


int.-exp{0). ==> “ON. 
int expl) 75> TIa 


int exp{9) ==> TIn 


However, a neater solution involves the single rule: 


int exp(I}) --> [C]; {C=<57, 
" Ov=<C i 
mamei; 277}. 


oe 
un 
~] 
li 
RE 
U} 
Q 
H 
H 
bt 
OF 
t4 
Te) 


Note that in this rule we have both a condition and a terminal with a variable in it. The construction 
'C) is the standard way of picking up data from the input stream. 


}1 
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The complete arithmetic expression parser should allow for integer expressions, additive 


expressions. multiplicative expressions anc bracketed expressions: 


exp(E) --> mul _exp(E). 
mul exp(E) --> add_exriz)- 
mul exp (Op (L,R)) ==> Re xp (L) ,»mul_op (Op) ,mul_exp (A) . 


id exp(E) --> int exr‘=)- 
d exp(Op(L,R)) -7> 2¢4_exp(L),add_op (Op) ,add_exp (>). 


int exp(E) 7? n(") excfE), Me 
ine exp-(2). ore (Cl, Desay S59 ASCL foe Te 
u""=E<cC, 


eda ppi) Sar Sara 

eieae a a 

Pe ODA), a e. ] % ASCII code for * is 42 
mil op(/} --> [47] ¢ ASCII code for / is 4. 


1.14.1 Using Definite Clause Grammars 

A grammar built up through the use of DCGs is used to parse strings through tne phrase 
primitive. This takes two oF three argumenis: a non-terminal, a string to parse, anc an optional 
“hird argument which returns the remaince: cf the string after the parse. 


We can use our arithmetic expression parser lo parse and evaluate some simple arithmetic 
expressions: 


-rase (exp (E), "2+3* (2-5; "),X is E? 
= <7 i 
4+(2,%*¢3,-(2,5))) 


m x'g 


As with other Prolog programs grammars can be used to generate strings from non-terminals as 
well as parse strings. Furthermore, the stings might actually be lists of symbols rather than lists of 
bytes. A complete system might use one grammar to parse characters into tokens and another 
grammar to parse lists of tokens into full parse trees. A thnird grammar might be used in the final 
stages of a compiler to actually emit the target code of a compiled program. 
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1.14.2 Translation of DCG Rules to Clauses 


DCG rules are translated into normal Prolog clauses by adding extra arguments to each of the 
non-terminals. Terminal symbols are translated to calls of the special built-in primitive ‘$C’, and 
conditions are not translated. The extra arguments link the output of each terminal/non-terminal to 
the input of the next. 


For example the rules for add_op are translated to: 


add op(+,S0,S1) :- '$C'(S0, 42, 51). 
add op(-,S0,$1) :- '$C'(S0, 4E, S1). 


The rules for int_exp are translated to: 


int_exp(E,S0,5S3) :- 'SC'(S0.45,5.29 4 
exp(E,S1l,£2:, 
VSO (S246 2% 55): < 
int exp(I,S0,S1):- 'SC*(SO0,C,5-), 
B C=<57, 
mer) "=<C ; 
name (I, [C] 


uN 
= 
A 
— 
— 
a 


w 1t 


[C] 


aO ole 


The translation of DCGs into Prolog clauses is performed whenever a file is consuited or wher 
a window containing DCG rules is (re)compiled. 


NOTE 
The exact translation of DCGs into Prolog clauses varies with different Prolog systems, althouc™ 


the syntax of a DCG rule is standard. The programmer should no: rety on the actual translatic> 
used. 


For a more detailed introduction to DCGs the reader is recommended to read Clocksin & Mellish. 
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1.14.3 User Defined Term Expansion 


DCGs are one example of a special pre-processor of Prolog text. The programmer may implement 
other alternative forms of pre-processing. for example a simple macro processor. This 1s 
implemente< through the special term_expansion hook. If there is a definition of this program 
then for each clause that is consulted or compiled (though not directly as serted) 
term expansion is called before actually compiling the clause. 


The format of 2 zerm expansion call is: 

term expansion (Input_tezm,Actual_clause) 
The Input term is the clause term as it is read during consult ete., and Actual_ clause ls 
the clause tha: will be compiled. 


NOTE 
Eserm expansion is defined then tne standard DCG processing will not be invoked. 


1.15 Edinburgh Syntax Program Windows 


An Edinburen syntax program window comprises a sequence of clauses or DCG rules, each one 
terminated with 2 full stop. All the clauses abour the same relation name must be conuguous and 
contained within one edit window, even i” the head terms have different arities. A program 
window car contain the definiuons for any number of different relations. 


The LPA MzsPROLOG™ Environment Guide contains a discussion on the recommended ways to 
use program windows for your source coce. 
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2 Control 


There are several control primitives for use in Edinburgh syntax programs: 


the negation operator not or \+ 

the conjunction and disjunction operators , and ; 

the conditional operator -> 

the cut primitive ! : 

fail, true and repeat 

the meta-call primitive call 

the generate and test pnmutive forall 

the set constructors findall, bagof and setot 
the general mapping utility map 


Most of these primitives take call terms as arguments ‘see the Syntzx chapter). If this call term is = 
conjunction. it should normally be enclosed in brackets. 
For example, 


noz (xX Likes bob, X likes: loc-c. 


2.1 not - negation operator 


not call 


or \+ call i ecg Ey) 
ARGUMENT 
call ' a call term 
DECLARATIVE READING 


call is false 
USE 


The negation as failure operator. 
not call succeeds if and only if ca11 fails. 


It is defined by: 


not X :- X,!,fail. 
not X 


2: Control 


ppp , - the conjunction operator 
CI C2 
DECLARATIVE READING 


z1 and C2 are true 


ARGUMENTS 
=. : a calì term 
or, : 2 call term 
USE 


(1000 xfy) 


Call C1 is evaluated and tren ZZ is evaluated. The conjunction succeeds if and only if both calls 


succeed. 


p, ; -~ the disjunction operator 
€25.CZ 

ARGUMENTS 
an : a call term 
s : a call term 

DECLARATIVE READING 


Ci or C2is true 


USE 


The call succeeds if either C1 or C2 succeeds. C1 is evaluated first. Only when all possible 
evaluation paths for Ci have been explored will backtracking lead to an evaluation of C2. 


A! evaluated in the disjunction not only prevents backtracking within the disjunction, it also 
prevents backtracking to find alternative solutions to calls that precede the disjunction in the clause 


or query in which the disjunction appears. 


A ! evaluated within the ©: branch also prevents the use of C2. 
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2.4 ~> - conditional evaluation 

test->call (1550 xfy) 
ARGUMENTS 

test : a call term 

call : a call term 
USE 


The -> call succeeds if and only if test succeeds and call succeeds. call can bea call to tne 
disjunction operator ;. In this case it is a conditional branch. 


As with ; a! evaluated in test or call not only has a local effect, but also the same effect es 2 


! evaluated just before the -> call. 


2:9 ! - backtracking control 
: 
USE 
This is the backtracking control primitive. After it nzs been evaluated in a clause a backtrack to ie 
' call will be interpreted as failure of the call C that invoked the ciause. That is. it prevents in2 


search for alternative solutions to any calls that precece the ! in the body of the clause, and it wi. 
also prevent the use of other clauses to try to solve Z. 


Placed at the top level in a query conjunction it will prevent backtracking to fing alternan.e 
solutions to calls that precede it in the query. 


See the descnption of the logical operators ; and -> for the effect of : inside these operators. 
p g p i 


2.6 fail or false -force a failure 
fail 
false 

USE 


Does not match anything, call always fails. 


2.1 true or otherwise -true 
true 
otherwise 

USE 


Call always succeeds. 
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2.8 repeat - backtracking loop entry 
repeat 
USE 


Call always succeeds and repzatedly succeeds each time the evaluation backtracks to the call. Irtis 
defined as: 


repeat. 
repeat :- rereat 
29 call - evaluate arcument as a call 


call (term) 


ARGUMENTS 
term > a call term or a Lis: of the form 
eS etn eee, Tase] 
DECLARATIVE READING 
erm Is true. 
ioe 


I: is equivalent to the call terz (except where term is ! orincludes ! - see below). 


arm can of course have as its functor any of the other logic operators including the conjunction 
cperator. 


A! evaluated inside term only has a local effect. It only affects backtracking to find alternative 
soiutions to calls that precede tne ! within germ. 
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2.10 forall - generate and test 


forall (gen, teast) 


ARGUMENTS 
gen : call term 
test : call term 
DECLARATIVE READING 


For all the solutions of gen, test is true. 
USE 
The forall primitive is a high level concept that can often replace recursion in a program. 


The following program defines a ‘prime number using forall. Itcan be usec to check ifa 
number is prime. A positive prime number X is a number that is not exactly divisidie by any 
integer Y, where Y is in the range 2S¥7<xX. This definition is formalised as: 


Dr ime tA) c= 
forall(in_range(2,X,¥), not divides (%,7)). 


in_ range and divides are defined as: 
in range (Startval, Endval,Startval). 
in_range(Startval,Endval,Val):- 
Newstart is Start ++ 1, 
Newstart < Endval, 
in range (Newstart, Endval, Vai). 
divides (Val1l,Val2):- 
#(Vall,ValZ,Divisor), *OorDivisor is Vall + Va lz 
integer (Divisor). 
This is nota very efficient program for checking prime numbers, but it is a correct one. 
DEFINITION 


forall (A,B):- 
not call({({A,not B)). 


After the evaluation of a forallall variables in gen and test are left unbound. 


19 


2: Control 


2.11 findall - construct a list of all the found solutions of a call 


findall(tarm, call, list) 


ARGUMENTS 

term : any term 

call : any call term 

list : a variable or list pate 
USE 


Vist will be unified with a list of instantiations of term, one for each successful evaluation of 
call. The instantiations of zerm correspond to the different solution bindings for the variables 
in call. At the end of the evaluation no variable in call will be bound. All the ‘local’ variables 
in cali ,the variables which do not appear in term, or in any other condition in the clause or 
query in which the findaiz is used, are implicitly existentially quanufied. 


For correct use, all ‘global’ variables of cz__, variables that are also used in other conditions in 
the clause cr query, should be pound to verizs:e free terms before the <indail is evaluated. 


example use: 


male (P), finda (X, (qi vesiP,Y,X),femaie (Y)),1L) 


binds L to the list of all the things X that zre given by male P to some female y. Tne Y is local to 
tne finda , the P 1s globai. 


PRAGMATICS 


This is faster than bagof (see below) and should be used instead of bagof when there will be no 
unbound global variables in the call for which solutions are to be found. 
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2.12 bagof - find the list of solutions to a query for different 
bindings of its global variables 


bagof (eterm, existential _call,list) 


ARGUMENTS 
list - variable, will be bound to a list of terms 
eterm : term 


existential call: term which is of the form 
vl*v2*..*vk*call ,k20 
where call is acall term and vi,..,vxk are 
variables in call. 
When k=0 just the ca 1 is given. 


LSE 


At the time of the call, ca_2_ will generally contain vanables. The variabies in cai. that are nc. 
in either eterm or the sequence vi,..,vk of variables preceding cai. are the globa. 
variables of the sagof call. vil,..,vk are the existentially quantified variables of cal. 


sagof partitions the list of all the values of eters for all the solutions of call by differen: 
solution values for these global variables. 


That is, suppose that in the space of all the successful evaluations of zall there aren differen: 
sets of bindings for its global variables. Then bagc 2 will backtrack giving n differerent answers. 
Each answer will comprise a set of bindings for the global variabies. and a corresponding value tor 
23st which comprises the instances of eterm for the different solutions of call that make tis 
assignment to the global vanables. 


For example, suppose that we have the following definitions of gives and male: 


gives (keith, sue, flowers) 
gives (keith, sue, earrings) 
gives (keith, cob, pen) 
qives (sue, xeith, guinness) 
gives (bob, sue, ink) 

gives (bob, keith, ball) 
male (keith) 

male (bob) 


The call: 
bagof (Person, Present^ (gives (Giver, Person, Present) ,male (Giver)),1L) 


can be read as: 


L is the list of Person(s) such that 
male Giver gives Person some Present. 


Its evaluation will generate two different answers: 


lt 
I 


L 
L 


[sue,sue,bob], Giver keith 
[sue, keith], Giver = bob 


tl 


Notice that sue appears on the first answer list twice because it appears in two different solutions 
of the two conditions paired with the same value keith of the global variable Giver. To obtain 
only one occurrence of sue we need to use setof described below. 
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2.13 setof - find the set of solutions to a query for different 
bindings of its global variables 


setof(etern, existential call, list) 


ARGUMENTS 
List : variable, will be bound to a list of terms 
eterm : term 


existential call : term which is of the form 
vitv2*..*vk*call ,k20 
where call isacalltermandvi,..,vk are 
variables in call. 
When k=0 just the call is given. 


CSE 


Exactly the same form of use as bagof described above. The difference is that the bindings for 


~=st will be ordered lists of terms without cupiicates. The terms are ordered by the @< primitive 
as a list of increasing terms. 


Taus, for the gives and male definitions cf the bas= = example, the two anwers to the call 


ts) 


etof (Person, Present^ (Gives (tiver, Person, Present), male (Giver)),L) 


will generate two different answers: 


L = [pob, sue], Giver = reith 
L ikeith,suesj, Giver DoD 
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2.14 map - map a relation over a list 


map(rel,inlist) 

map(rel,inlist,outlist) 
map(rel,inlist,invalue, outvalue) 
map(rel,inlist,outlist, invalue, outvalue) 


ARGUMENTS 


rel : relation name or unary compound term 
inlist : list 

outlist : variable or list 

invalue : term 

ovt value : variable 


USES 


For each use of map, the term rel may be either a relation name or a unary compound term oi tn: 
form 


réin (arg) 


whose principal functor rein is a relation name. 


1. Two argument use. If -+2 is a unary relation name. inis call wil test ifall the elements oia ~ 
inlist sausfy rel. 
For example. 


Per iinteces, 12-5739 )) 
succeeds. 


If rel is a unary compound term of the form reln «arc; then the call tests if all the elements +1 
of inlist sausfy reln(arg,el). 
For example, 


mapi> {10y 12325 51 opal) 
succeeds since all the numbers in the given list are less than 10. 


2. Three argument use. If inlist is given, map will produce a list outlist such that esca 
element of outlist is in the relation rel to the corresponding element of inlis:. 
Alternatively, map may be used or to check that a given ourlisc is in this relationship :o 
Insist, 
For example, the call 

map (charof, {[a,b,c],List) 
will bind List to the list {97, 98, 99]. 
The call 

map (*(8),[1,2,3,4],List) 


will bind List to {[8,16,24,32]. 
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3. Four argument use. The given rel is applied to ‘accumulate’ the elements of inlist using 
invalue as the initial value of the cumulated term. The variable cutvalue is bound to the final 
cumulated term. 


For example, the call: 
Map (+, 1525.3; 450))0s Val) 
will bind Vai to the sum of 1,2,3,4 and 5. 


4. Five argument use. The given rel is applied both to produce an outlist from inliszc. 
and to ‘accumulate’ the elements of inlist using invalue as the initial value of the cumulated 
term, binding the variable ouc ve lue to the final cumulated term. 


For example, the call 


f- ~ 


WecGus (Gls Tarer dra ly oy Ur Nal) 


where the definiton of ts 15 


a E ied =o ~~ rva $p 

ZE eee —i > f L£; » -7 V2) = 
Be 2e EL A aa 
7^ Poa 779 —- 
TO me = Se ee 


oF 


“ill Ona = to (26,22. end Val toin 
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3 Type Primitives 


There are seven type checking primitives: var, monvar, atom, atomic, 
number and float. 


3.1 var - test for variable 
var (arg) 


ARGUMENTS 


ar 


14} 


: any term 


DECLARATIVE READING 


3.2 nonvar - test for not being a variable 
nonvar (arg) 


ARGUMENTS 


- ya 
ae 


: any term 


Mi 


DECLARATIVE READING 


arg is notan unbound variable. The call fails if arg is an unbound vanable. 


3.3 atom - test for atom 
atom(arg) 


ARGUMENTS 


= 


tL) 


: any term 
- DECLARATIVE READING 


arg is anatom. The call fails for any other type of argument. 


integer, 


3 : Type Primitives 


3.4 atomic - test for atom or number 
atomic (arg) 
ARGUMENTS 
arg : any term 
DECLARATIVE READING 


arg isan atom or a number. The call fails for any other type of argument. 


3.5 integer - test for integer 
integer (arg) 
ARGUMENTS 
arg : any term 
DECLARATIVE READING 


arg isan integer. The call fails for any other type of argument. 


3.6 number - test for number 


number (arg) 
ARGUMENTS 

arg : any term 
DECLARATIVE READING 


arg is anumber - an integer or a floating point number. The call fails for any other type of 
argument. 


3.7 float - test for non integer number 


float (arg) 


ARGUMENTS 
arg : any term 
DECLARATIVE READING 


arg is anon-integer number. It has a fraction part. The call fails for any other type of argument. 
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4 Metalogical Primitives 


In addition to the usual arg, functor and =. . term manipulation primitives, MacPROLOG has 


two primitives tohollow and toground for converting between ground terms and hollow 
terms. 


In a ground term, variable positions are represented by variable name atoms, in a hollow term they 
are represented by variables. The variables of a hollow term can be instantiated by unification, the 
variable names of a ground term will only unify with exactly the same variable name atoms. 


The toho low primitive can be used to convert into hollow terms the ground terms that are read 
in by the various ground read primitives, e.g. greaz. The togrce=nd primitive can be used to 
ground a hollow term prior to pretty printing or some other recursive traversal where it is 
convenient not to have to deal with the case of unbound variables. It copies the nollow term 
replacing variables by underscore variable names or any given bindings. 


The standard Edinburgh numbervars is also available. This grounds the variabies of a term 
without copving. The primitive varsin finds all the variables in aterm. 
4.1 arg - argument selector 


arg(N,T, arg) 


ARGUMENTS 
N : integer 
T : non-vaniable term 
arg : any term 
DECLARATIVE READING 


arg iS the Vth argument of term T. 
USE 
arg is unified with the N 'th argument of T. It can be used to retrieve or check the argument value. 
Example use: 
arg(2,app({2}, (3,4},2),Arg) 


binds Arg to [3,4] 


4: Metalogical Primitives 


4.2 functor - term decomposition/construction 


functor (T, F, N) 


ARGUMENTS 
T : any term 
F > atom or variable 
N : integer or variable 
DECLARATIVE READING 


T is aterm with functor F and arty N. 


lf > 4s a non-variable term. tnen the primitive finds the functor and arity of T and unifies their 
respective values with F anc iN. 

ne functor cf a list iS. and us ante 1s 2. 

a functor Ci an atom or number is its wae and its arity 1s 0. 


-ate ‘me A — ` fuer - o bd lard 
e Oh © oes 4 Ps Oo ee a NE et 

mo- ae mh a y bee 

Gio! 10 ETS añd kae 


1 oo 46 9 veriable, then F and © must be an atom and integer respectively. The pnmitive binds T 


FE ia T A WIE Faneto rFwith 3) new and cifterent variables as arguments. 


rer example: 


Serer ep a tT. jee oye 


binds T to i:kes(_1,_2). 
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4.3 =.. -list to term conversion 


term =.. list 


ARGUMENTS 
term : compound term or variable (if list nota variable) 
list : list or variable (if term not a variable) 
DECLARATIVE READING 


list is alist comprising the functor of term followed by a list of its arguments. Traditionally 
this primitive is pronounced ‘univ’ after the same primitive in the original PROLOG implemented in 
Marseille in 1972. 


USES 


If term is a variable, a compound term is constructed from iist. 
If list is a variable, a list is constructed from tern. 
If both are non-variables, the list form of zerm is constrected and united with lier 


Example uses: 

f (X,7) =.. Y 
binds Y to [f, X, 7] 

Z =.. [lixes,X,mary! 
binds Z to i: kes (X, mary) 

PTI. Se rrop a 
binds F to £, Xto 3 and ¥to7 
PRAGMATICS 
Because MacPROLOG has more powerful meta-call faciiues than o:ner Edinburgh syntax systems 
there is no need to use this primitive for the construction of calls. Tre availability of the relation 
name meta-variable means that the relation name of a cail can be changed without the use of this 
primitive and the fact that a meta-variable can be bound to a list at the ume of the call means that it Is 
not needed even when the number of arguments is also changed. Consult the section on 
meta-variables in the Syntax chapter. 
However, if you want to preserve portability, you should continue to use this primitive to construct 


calls. If you are only developing for use with MacPROLOG it is more efficient if you avoid its 
use. 
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4.4 varsin - find all the variables in a term 


varsin(term, varlist) 


ARGUMENTS 

term : any term 

varlist - variable, will be bound to a list of all the variables in terr 
USE 


To find the variables in a term. 


4.5 tohollow - convert a ground term to a hollow term 


tohollow (ground term,hollow_term,varnames) 
~chollow (ground term, hollow_term, varnames, vars) 


ARGUMENTS 


Srcund term : variable free term 

hollow_term - variable. will become hollow copy of ground_tér= 
vernames - variable, or a list of atoms 

VErs - variable, will be bound to the list of variables in ho--ow_terr. 


that have replaced the variable names in ground term 


w w = 


USES 
l. Three argument use, varpams s a jist oF atoms, Only the atoms in the varzares list of 


atoms are replaced by variables in the hoiiow_term copy of ground_term. Any atoms Can 
be on the varnames list. For example, the call 


“onollow(likes (keith, 'rPerson'):- 
likes('rexrson', 'PROLOG'), 
Hollow, ‘’ryerson')) 
will bind Ec iow to 

¿xes (keith, 1):-likes {_1, "PROLGS! 
where 7 is a variable but ‘PROLOG’ is still an atom. 


The main use of this form of the call is to convert a term and its associated list of variable names 
that has been read in using prompt _gread or gread, OF retrieved from the data base using the 
two argument form of clause, into a hollow term that can be used in an evaluation. 


2. Four argument use. Essentially the same as the above three argument use excep: that the list of 
variables in hollow term that have replaced the atoms on varnames is also returned. The i-th 
variable on vars is the replacement for the i-th variable name on varnames. 

This is useful if you want to subsequently output bindings for these variables using the original 
variable names. 
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4.6 toground - convert a hollow term to a ground term 


toground (hollow term, ground term) 

toground (hollow term, ground_term, varnames) 

toground (hollow term, ground _term, vars, varnames) 

toground (hollow term, ground _term,vars, 
varnames, usednames) 


ARGUMENTS 
hollow_term : any term 
ground_term : a variable, will become hollow_term 
with all the variables replaced by 
unique underscore variable names 
varnames : variable, or list of atoms 
vars : variable, or list of variadies/terms 
usednames ‘ variable, will be bound to the list of ail the variable names in 
ground term that have replaced variables in hoi-cw_terx 
USE 
1. Two argument use, Simple use to convert any term into a variable free term. ground term 


is bound to a copy of hollow term in which all the variabies are replaced by new atoms 
beginning with underscore. Different variables are replaced by Cilerent underscore names. ano 
there will be no clash with any atom that begins with underscore which already appears :7 
hollow_term. 


2. Three argument use - varnames a variable. varnames will be bound to the list of all ire 
underscore variable names that have been used to repiace variables in .citow_tern. 


3. Four arcument use - varnames and vars both variables. Same as the three arc 2 
except that the corresponding list of the replaced variabies is also retumed as the bincins lortar. 





4. Five arcument use - varnames a list of atoms. vars a iist of variables {opedise so 
hollow term, usednames a vaniable. 


The varnames list of atoms will be used to replace the vanabies of vars in he-lcw_ cess 
the order in which they are given - the first variable of vars is rer.cced by the first alom on tn2 


varnames list, and soon. vars and varnames must be the sare length. 


If there are more variables in hollow _termthan given in vars. new underscore names zre 
given to the extra variables. 


More generally, the elements of vars can be any terms. Non-variabdle terms on vars. and in2 
corresponding atoms on varnames are ignored - but the lists must still be the same iength. This 
relaxation allows lists of names and variables returned by some prior use of tohollcw to be used 
as arguments to toground without having to remove variables that mav have been bound by tne 
intervening evaluation. 


Finally, usednames is bound to the complete list of the actual variable names that have been used 
to replace variables in hollow_term 
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4.7 numbervars - number the variables in a term 


numbervars (term, start,next) 


ARGUMENTS 
term : term 
start : integer 
next : variable 
USE 


The variables in the term term are instanuated to terms of the form 
'SYAR' (n) 


where n is an integer. The first value of n to be used is given by the start argument. The next 
distinct variable of term will be 'SVAR' (n+1), and soon. 


When all the variables of term have been thus instantiated, the next argument wil. be bound to 


the next vaiue of n that would be used. i.e. the last variable of term has the form 
‘SEVER’ (nmext-l). 


4.8 phrase - test if list can be parsed as a phrase of some type 


phrase (type, list) l 
phrase(type, list, remiist) 


ARGUMENTS 
tyre : non-terminal symbol 
Eee : list of terms 
remlist : remaining list of terms 
DECLARATIVE READING 


Tne sequence of terms in 22s: can be parsed into a phrase of the given type. 
In the three argument form. the first part of the sequence of terms in list can be parsed into @ 
phrase of the given type, leaving the sequence of terms in remlist. 


‘See the section on Definite Ciause Grammars in the Syntax chapter.) 
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5 Standard Arithmetic 


MacPROLOG supports both integer and floating point arithmetic. There are four primitives ++ ~- 
xx and // that require integer arguments. All the other primitives will take either integer or 
floating point arguments. Automatic conversion between integers and floating point numbers takes 
place wherever necessary. 


This chapter describes the four standard arithmetic operations, and the arithmetic expression 
primitives is,=:= and =/=. Number comparison primitives are also included here. 


The trigonometric functions and bit manipulation pmmitives are described in the Extendec 
Arithmetic chapter. 


ible error 


Where an arithmetic operation results in arithmetic emer, MacPROLOG signals an “Anthmet:: 
error" (error 1). You will get the error when overflow cr underflow occurs, or if wou attemp on 


operation with an undefined result such as dividing zy % or taking ihe square root of a negats 
number. Te error will cause a run time error hanci:n.2 tackage to be invoked whicn displays ine 
offending cai! with a special atom in place of the variaz.2 argument of the call. The atom indicatie: 
the type of error. For example, œ indicates anthmet:c overflow and -æ arithmetic uncertlow. A. 
the other atoms begin with the letters NAN standing er Not A Number. 


Accuracy 
MacPROLOG uses 80 bits of accuracy in its floating point anthmenic calculations. 


The integer arithmetic primitives use 24 bits of accuracy. 


5 : Standard Arithmetic 


§.1 is - expression evaluator 

expl is exp2 {700 xx) 
ARGUMENTS 

expl exp2 : arithmetic expressions 
DECLARATIVE READING 


is should be read as an equality test that its two expression arguments have the same value. 


USES 


(1) When one of the arguments is a variable v the other argument is evaluated and v is bound to 
its value, e.g. 


X is 7 + 8e >” sin(yY) 


(2) When both arguments are non-variabie expressions they are both evaluated and their values 
tested for equality. 


EXPRESSION SYNTAX 


An arithmetic expression is 


a variable 
OT a number (ora list of one number: {[n] isequivalentton ) 
or a term which is constructed using the variables. numbers and 
1¢ predeclared operators: 


op(300, xfx, [mod}). 
OPS OOs Vix LESNA I) a 


ODIS DIri [Tyee itt en!) 
On 400; Vix 5 el RG eee: 
and terms of the form 
rel(expl,exrzZ) 
such that a call of the form 


rel(expl,exrZ, val) with val a vaniable 


will bind val to anumeric value. 


The list of one number [n] evaluates to n. It means that a string of one character "c" (which iS 2 
list of one number : the ASCI code for < -) is equivalent to the ASCI code for c in an arithmetic 
expression. This equivalence is particularly useful when using the puz and skip primitives (see 


+ 


Chapter 11), both of which can have arithmetic expression arguments. 
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5.2 + addition 
+ (numi, num2, num3) (500 75x) 
ARGUMENTS 
numi : number 
num2 : number 
num3 : variable 
DECLARATIVE READING 
numl + num2 = num3 
USE 


Only one three argument use of + is permitted: where we are adding two numbers together to 
produce a result number. An error will occur if these conditions are not met. 


5.3 - subtraction or minus operation 

-(numl, num2, num3) (S00. 32) 

-({numi,num3) (S500 <x) 
ARGUMENTS 

num] : number 

numZ : number 

num3 : variable 
DECLARATIVE READING 

numl ~ numZ2 = num: or Un: = se 
USES 
Only one three argument use of - is permitted: where we are subtracting two numbers to produce 
a result number. 


There is only one two argument use: when the negative of a given number is to b returned. 
An error will occur for any other attempted use. 
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5.4 * multiplication 
*(numil,numZ, num3) 
ARGUMENTS 
num : number 
num? : number 
nora : variable 
DECLARATIVE READING 
numl * num? = num3 
USE 


(400 yfx) 


Oziv one use of * is permitted: where we are multiplying two numbers together to produce a result 
number. An error will occur if nese condcitons are not met. 


(Fe 
tJa 


+ or / division 


+(numl,num2,num3) 
/{(numi,num2,num3) 


ARGUMENTS 

eh ‘number 

Rox? ‘number 

eirag : variable 
DECLARATIVE READING 

nuni + numZ = nums 
LSL 


(400 yfx) 
(400 yfx) 


Oniy one use of + is permitted: where we are dividing one number by another to produce a quotient 
umber. An error will occur if these conc:uons are not met. 
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5.6 ++ integer addition 
++ (numl, num2, num3) (S00 yfx) 
ARGUMENTS 
numi : number 
num2 : number 
num3 . : variable 
DECLARATIVE READING 
numi +num2 = num3 
USE 


Only one use of ++ is permitted: when we are adding one integer to another. An error will occur if 
numi and num2 are not integers. 


PRAGMATICS 


The integer forms of +, -, * and + are supplied for increased efficiency. Use them when you 
know that all the numbers involved will be integers. 


S -- integer subtraction 
-- (numi, num2, num3) (S00: x) 
ARGUMENTS 
numl : number 
num2 : number 
num3 : variable 
DECLARATIVE READING 
numl -num2 = num2 
USE 


Only one use of -- is permitted: where we are subtracting one integer from another. An error will 
occur if num1 and num2 are not integers. 
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5.8 ** integer multiplication 
** (numi, num2,num3) (400 yfx) 
ARGUMENTS 
numi : number 
num2 : number 
nuns : variable 
DECLARATIVE READING 
numi * num2 = num3 
Los 


Only one use of ** is permitted: where we are multiplying one integer by another. An error will 
occur if numi and num2 are not integers. 


z9 // integer division 

// (num, divisor, quotient) (400 yx) 
ARGUMENTS 

pees : integer 

divisor : intecer 

Gectient : vanade 
DECLARATIVE READING 

cucotient is the integer part of the result of dividing num by divisor 
LSE 


Only one use, to find the whole number of umes one integer divides another. An error will occur if 
-umand divisor are not integers. 


For example, the call 
fF A 2B, Teh) 


will bind X to 5. 
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§.10 mod - the modulus of one number relative to another 


mod(num, div, rem) (300 xfx) 
ARGUMENTS 

num ‘a number 

div : anumber 

rem : a variable 
DECLARATIVE READING 


num = div * Q + rem, rem <S div and Z aninteger 
USE 
Only one use, to find the modulus of given num relative to div. 
For example, the call 
| Mod (ly joer) 


will bind R to 2. 


5.11 =:= - expression equality test 

expli =:= exp2 LIC 452) 
ARGUMENTS 

expl exp2 : arithmetic expressions, see the cescription of is 
USE 


To evaluate exp1 and exp2 and confirm that they have the same vaiue. This operator is reduncin: 
since this operation is also performed by the MacPROLOG is. I: is included for compatbi:::: 
with other Edinburgh syntax systems. 
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5.12 =\= - expression inequality test 

expl =\= exp2 (700 xfx) 
ARGUMENTS 

expl exp2 : arithmetic expressions, see the description of is 
USE 


To evaluate exp1 and exp2 and confirm that they do not have the same value. It is equivalent to 


nect expl =:= exp2. 
AK < - check if a number is less than another number 

nunberl < number2 (700 xfx) 
ARGUMENTS 

Hother] “nimbi: 

nuyoerZ “number 


Checking only. < must be called with both arguments given. In this case the call succeeds if the 
first number is numerically less than the seconc number. 
For example, z<2 is true, 251s -1<1. 


oe 
utneither .2<S nor 4.4<4.4 iS true. 
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5.14 > - check if a number is greater than another number 


numberl > number2 (7CC xfx) 
ARGUMENTS 

number] : number 

number2 : number 
DECLARATIVE READING 


numberl > number2 
The first number is greater than the second number. 


USE 


Checking only. > must be called with both arguments given. In this case the cal! succeeds if i12 
first number 1s numerically greater than the second number. 


5.15 2 or >= -check if a number is greater than or equal to another 
number 

numberl 2 number2Z eg: ALN) 
or mnumberl >= number2 Cio BERI 
ARGUMENTS 

nusberl : number 

number2 : number 
DECLARATIVE READING 


numberl 2 number2 
The first number is greater than or equal to the seconc number. 


USE 


Checking only. 2 must be called with both arguments given. 
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5 : Standard Arithmetic 


5.16 < or =< - check if a number is less than or equal 
to another number 

numberl < number2 (700 xfx) 
or number =< number2 (700 xfx) 
ARGUMENTS 

nurber]l ‘number 

nurbperZ : number 
DECLARATIVE READING 

number] < snumper2 
USE 


Checking only. < must be catied with both arguments given. 
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6 Extended Arithmetic 


6.1 sqrt - the square root of a number 


sqrt(num, root) 


ARGUMENTS 
num : number or variable (provided root is a number) 
root : number or variable (provided num is a number) 
DECLARATIVE READING 
num = root *root 
USES 


1. Taking a square root. If num isa number and z227 isa variable then the rccz argument is 
bound to the square root of num. For example, the call 


sart (9, 4) 


results in X being bound to 3. The num argument should be positive, otherwise the “Not s 
number error’ (1) is signalled. 


2. Squaring a number. The sqrt primitive can be used to square a number. If the roc: 
argument is a number and the num argument is a vancdle, num will be bound to rocz squared. 


eet 


checked to see that itis root squared. 


6.2 abs - the absolute value of a number. 


abs (num, abs) 


ARGUMENTS 
num : number 
abs : variable 
DECLARATIVE READING 
[num | = abs 
USE 


Only one use of abs is supported: to take the absolute value of a number. 
For example, the call 


abs (-3,A) 


will bind A to 3. 


6 : Extended Arithmetic 


6.3 int - truncate a number towards zero 


int (num, int) 


ARGUMENTS 


num : number 
ant : varlabie or integer 


DECLARATIVE READING 


= - & 


int is the nearest integer to num between 0 and num. 
LORS 


TU 


A ung Towards Zere. Io ing is a variable it will be bound to the nearest integer to the 
number num (truncating towards zero). For example, the call 


peel SNe ip D 
wid bing X to 2. The call 
Leet Sas seat fan) 
will bind 2 to the integer -22<572. 


>. Dhecking. int will succeec if int is an integer and it is the nearest integer to the number nuz 
wren num is rounded towards zero. For example, the call 


Ie CS 2 cs) 
wiU Succeed. The call 
inct(3<6;,4) 


will fail. 


6: Extended Arithmetic 


6.4 sign - the sign of a number 


sign (num, sign) 


ARGUMENTS 

num : number 

sign : variable, or -1 or 0 or 1 
DECLARATIVE READING 


sign = 1 if num is greater than 0, 
sign = 0 if num is equal to 0, 
sign = -1 if num is less than 0. 


USES 


1. Finding the Sign of a Number. If num is a number (integer or floating point). and sign is o7 


unbound variable, the variable will be bound to the sign of the number. 
For example, the call 
signt=3;5) 
binds S to -1, 
sign (0, X) 
binds X to C, and 
sign(25.67,2) 


will bind Z to 1. 


A 


2, Checking the Sign of a Number. If both num and sign are given, sign wit succeed if nur 


has sign sign. 
For example, the call 

sign (21.4,1) 
will succeed. The call 

sign (21,-1) 
will fail. 
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6: Extended Arithmetic 


6.5 ln - natural logarithm/anti-log 


in(number, log) 


ARGUMENTS 
number  :number or vanable (:f logis not a variable) 
log : number or variable (if number is not a variable) 
DECLARATIVE READING 





C.6 pwr - power tc any base 
pwr(n,p,n_tc_p) 
4° GUMENTS 
Fs : number or vanabie iiin to_ pis not a variable) 
a > number 
moto p number or variable (if nis not a vanable) 


DECLARATIVE READING 
n top = n? 
Aero 
:. To compute a power. nang o are given. to p isa variable. 
For example, the call 


Dwr (27-35%) 


will bind X to &. 


2. To find a base. p andn_tc_p are given, n isa variable. 
For example the call 
pwr (N,4,81) 


will bind N to 3. 
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6 : Extended Arithmetic 


6.7 sin - the sine of an angle in radians 


sin(angle, sine) 


ARGUMENTS 

angle - a number or variable (if sine is a number) 

sine : a number in the range -1 .. 1, or a variable (if angle is a number) 
DECLARATIVE READING 


sine =sine(angle ) where angle is expressed in racians. 
USES 


1. Finding the sine. In this case the angle argument must be given in radians, and the sins 
argument will be bound to the value of sine(angle). 


2. Finding the arcsine. If angle is a variable and sine is given. angle will be given the 
arcsine value in radians in the range - 71/2 to 7/2. 


NOTE 


z radians is 360°. The primitive pi returns the value of = used by MacPROLOG, anc 
de seep may be used to convert between degrees and radians - see below. 


6.8 cos - the cosine of an angle in radians 


cos (angle, cosine) 


ARGUMENTS 

angle - a number or a variable (if cosine is numter) 

cosine :anumberin the range -1.. 1 ora vanabie ue angle is number) 
DECLARATIVE READING 


cosine =cosine(angle ) where angle is expressed in radians. 
USES 


1. Finding the cosine. In this case the angle argument must be given in radians, and tne 
=osine argument will be bound to the value of cos(angle). 


given, then angle will be bound 


2, Finding the arcosine. If angle is a variable and ccsine 
- ~~: 
ib: aw dh: 


1S 
to the value of the arcosine of cosine in the range - to 72. 
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6 : Extended Anthmetic 


6.9 tan - the tangent of an angle in radians 


tan(angle,tangent) 


ARGUMENTS 
angle -a number or variable (if tangent is a number) 
tangent :anumberor a variable (if angle is a number) 





6.16 deg rad - conversion between degrees and radians 


deg rad(d_angle,r_angle) 


< angie: number of degrees. or a variable 


r angie  : number of radians, or a variable 
DECLARATIVE READING 
r angie = d_angle * 2n/360. 


GSES 


’ Converting to radians. The d angle argument must be given in degrees, r_angie will 
become the equivalent value in radians. 


2, Converting to degrees. The r_angle argument must be given in radians; d angle will 
become the equivalent value in degrees. 


3. Checking If both arguments are given as numbers, deg_rac succeeds if r angle is 
3 angle converted to radians, and fails otherwise. 
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6: Extended Arithmetic 


6.11 pi - the value of x 
pi(pi_val) 
ARGUMENTS 


pi_val : variable 


USE 


The variable pi_val will be instantiated to the value of z used by MacPROLOG. 


6.12 /\ - logical and of two integer bit strings 


/\(int1,int2,and_int) (S60 vx) 
ARGUMENTS 

intl : an integer 

Inez : an integer 


and int :avanable 


DECLARATIVE READING 


and int is the integer that results from taking the logical and of the bit strings of the integers 
intland int2. 


6.13 \/ -logical or of two integer bit strings 


\/(int1,int2,or_int) (500 vEx) 
ARGUMENTS 

ined : an integer 

int2 : an integer 

Or int : a variable 
DECLARATIVE READING 


or int isthe integer that results from taking the logical or of the bit strings of the integers 
intl and int2. 
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6: Extended Arithmetic 


6.14 \ - logical complement of an integer bit string 
\(intl,int2) (500 fx) 
ARGUMENTS 
inel : an integer 
inez : a variable 
DECLARATIVE READING 


:-+2 is the integer that results from complementing each bit of int1. 


6.15 » or >> - shift right 


» (integer, shift, result) (400 yx) 

>> (integer, shift, resuit) (400 vay) 
ARGUMENTS 

integer ‘:animteger 


aisle ape : a positive integer 
ste. —pavanable 


DECLARATIVE READING 
sult is the integer which has the bit pattern representation of integer shifted shift b:: 


positions to the nght. 


6.16 « or << - shift left 


«(integer,shift, result) (400 yzx) 
<< (integer, shift, result) (400 yx) 
ARGUMENTS 
integer ‘:aninteger 
Syet : a positive integer 
result ‘a variable 
DECLARATIVE READING 


~a5ult is the integer which has the bit pattern representation of integer shifted shit: 
positions to the left. 
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7 Comparison of Terms 


7.1 = - unifiable 
tl = t2 (700 xfx) 
ARGUMENTS 
blip te : any terms 
DECLARATIVE READING 
tlandt2 are equal. 
USE 


To test that two terms are umflable. Itis defined by: 


A= X. 
ded \= + not unifiable 
tl \= t2 (TUU 222 
tl z t2 GOD An] 
ARGUMENTS 
Erea : any terms 
DECLARATIYE READING 


z1 and tZ are not equal. 
USE 
To test that two terms are not uniftable. It is equivalent :o 


Ses tI = Ee: 


7 : Comparison of Terms 


7.3 == - the identity tester 
til == t2 (700 xfx) 
ARGUMENTS 
Eltz : any terms 
DECLARATIVE READING 
t1 and t2 are syntactically identical. 
USE 


To test that two terms are identical without the need to bind variables in either term. The call will 
only succeed if the terms have identical structure and contain the same numbers, atoms and 
variables. 


~~2 


Aa 


\== - the non-identity tester 
tl \== t2 (70C xx) 
ARGUMENTS 
Eltz : any erms 
DECLARATIVE READING 
-1 and t2 are not syntactically identical. 
USE 


it is equivalent to the call 
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7 : Comparison of Terms 


75 unify - unification with the occurs check 
unify (t1, t2) 

ARGUMENTS 
ti,t2 : any terms 


USE 


This is the same as = except that the uni £y only succeeds if t 1 and £2 can be unified without any 
variable being instantiated to a term containing itself. 


For example, both the calls 


fco7(X%) = Y 
and 


rae y CEOO C4) 7-23 


will succeed 2nd bind Y to =co(X). 
However, the call 


froo(X) = X 
would result in % being bound to the “infinite” term 


#a= (foo (Lact 


but the cali 
unify (£00 (X%) , X) 


will fail. 
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7 : Comparison of Terms 


7.6 compare - general term comparison 


compare(rel,termi, term2) 


ARGUMENTS 
rel : variable or one of <, =, > 
termi > any term 
term? > any term 

CSES 


1. If rel is given the two terms are compared as specified. = forces a == comparison. 


^. If rel is a variable the terms are compared and rel is bound to <,= or > to indicate the 
result. 


Tne order relation used 1s: 

variables < atoms < lists < compound terms 
\ ariables are compared by their machine aacress. 
Numbers are compared by value using the < primitive. 


he empty list is shorter then any non-empty list. If two non-empty lists have the same first element 
en their tails are compared. 


3 +4 


Compound terms are ordered first by arity. then by the name of their principal functor, and then by 


e--n of the 2reuments in left to mght order. 
= = 


Atoms are compared lexicographically using the international character code convention. This 
oncracter ordering is somewnat different to the ASCII ordering for characters: when two atoms are 
compared inidally, case is ignored: that is lowercase a and uppercase + are both regarded as being 
smaller than lowercase b and uppercase È. 

In norma! ASCIla < b andA < Bbut= > a). 


| 


here two letters differ only in case then the uppercase letter is ‘smaller’ than the lowercase letter. 
Sc. the following inequalities hold for atoms: 


p 


5 < ac Zim < ab a= =< AC 


The < predicate also takes into account certain character decorations. Initially, accented characters 
sucn aS a & or é are treated as being the same as the unaccented character, except that when letters 
ciffer oniy by a decoration then the ordering 1s as follows 


a<a<ca<é< 4< <a 


pn 


(and similarly for other letters). 
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7 : Comparison of Terms 


Fet @> - greater than term comparison 

tı @> t2 (700 xix) 
ARGUMENTS 

tl, E? : any terms 
USE 


Equivalent to compare (>,t1l,t2). 


7.8 @< - less than term comparison 

{1 @< t2 (700 xix) 
ARGUMENTS 

tlta : any terms 
USE 


Equivalent to compare (<,¢1,t2). 


7.9 @>= - greater than or equal term comparison 

tI @>= t2 (700: 227) 
ARGUMENTS 

E : any terms 
USE 


Equivalent to not compare (<,t1l,©2). 


7.10 @=< > less than or equal term comparison 
ti @=< t2 ( T00 3x) 
ARGUMENTS 
Ci; te : any terms 
USE 
Equivalent to 


not compare (>,t1,t2). 
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7 : Comparison of Terms 


7.11 mem - find a subterm corresponding to a path 


mem(term, path, subterm) 


ARGUMENTS 
term : any term 
path : list of positive integers 


subterm : vanable 
USE 
The length of the path argument specifies the depth of the subterm, and the integers in the path 
list specify elements of successive suDterms. 
For exampie, the call 


mem(foo(a, bar (X,b)), (2. ,M) 


will bind % to foo. 


Tne call 

mem(foo(a, ber (X,b)), [2,23,™M) 
will bind M to bar. 
The call 


mem(foo(a,bar(X,b)), is,3],M) 
will bind & to D. 


The call will fail if the path refers to a non-existent subterm. 
For examp!e, both the calls 


mem(foo(a,bar(X,b)), (2,8) .™) 


and 
mem(foo(a,bar(X,b)), {5,2,3),™) 


fail. 
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7 : Comparison of Terms 


7.12 sort - sort a list 


sort (list, sortedlist) 
sort (list, sortedlist,keyselect) 
sort(list, sortedlist,keyselect, dir) 


ARGUMENTS 
list : any complete list of terms 
sortedlist : variable, will become sorted version of list 
keyselect : list of positive integers 
dir : 1 or -i, specifies direction of the sort 
USES 


1. Two argument call. scortedlist is bound toa sorted copy of iist with terms in ascendinz 
order. The terms are compared using the term comparison primitive 4<. 


2. Three argument call. sortedlist is bound to a sorted copy of List with terms in 
ascending order. | 

The terms are compared by comparing a key in each term using the term comparison pnmitive 3<., 
The key is selected using the keyseiec: list of integers. The length of thts list indicates the 
depth of the key. Thus [2,2] selects a key at depth 2. The 1 selects the functor (or head element: 
of the compound terms (or lists) that are the elements of List and then the 2 selects the first 
argument (or the second list element) of this term to give the level two xey. 


Example: 
secre ({e(hi2; 2) }% k(5(4,3,8), ", Ogi Sg ier he X, ESEYE 


binds zito: aowa ror aaora he Sees 


~ 


an 


)) ? because 1<3<5. 
A value of 1 onthe keyse_lect list of integers selects the functor of a compound term. So the 


keyselect list [1] sorts the terms on list by comparing their functors. keyss-ect can 
also be the empty list. 


The call 
Sort (13st; 2crtedlis2, [)) 
is equivalent to 
sort (list, scrtediist}. 
3. Four argument call. Same as the three argument call except that the last argument specifies the 


direction of the sort. -1 specifies an ascending order som (the default if this argument 1s not 
given) and 1 specifies a descending order sort. 


NOTE Remember that in an operator term the operator will be the first element of the term, even 1 
it is written as if it were the second element. For example. the term 


3+3 


is actually treated as + (3, 5). 
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7 : Comparison of Terms 


7.13 keysort - sort a list of terms of the form t-t’ using fas a key 


keysort (list, sortedlist) 
keysort (list, sortedlist, dir) 


ARGUMENTS 
list : any complete list of terms of the form t-t ' 
sortedlist : variable. will become sorted version of list 
dir : 1 or -1. specifies direction of the sort 

USES 


. 1. Two argument call. scrzedlist is bound toa soned copy of list. The terms are 
compared using the first argument t of the operator term t-t ' as the key. 


For example, 
Kevsort ([3-sam,2-bil1.l,ř-andrew,,X) 
binds X to (2-bill, 3-saéz., 5-anares.. 


2. Three aroument call. Same as two argument call excepi that the list is in descending order if cir 
has value i. A dir value of -1 specifies ascending order. 


NOTE 
The call 

keysort ([32-sam, 2-bi.., >-andrew,; ,X) 
is equivalent to the call 


sort ([3-sam,2-bill, 5-andrew) ,%, [2]) 


This is because the operator terms of the form t-t ' are treated as being of the form - (t, t '). 
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7 : Comparison of Terms 


7.14 append - concatenation relation for lists 


append (listi, list2, list3) 


ARGUMENTS 
listl : list or variable 
list2 : list or variable 
list3 : list or variable 
DECLARATIVE READING 


list3 is list1 followed by list2 
DEFINITION 
The program append 1s defined as follows: 


acoend(({],21,1L). 
espend( (EE) L1)5b2, [Bia] t= s2eesa (bi, oz, 53). 


"a e ee i 
- - 


For example, the call 

coena liares 14.22 6ly -Al 
will bind % to the list [1, 2, 3,4,5,6.. 
The call 

acpend(A, {elBl, [a; b; De; rii. 


will bind A to the list [a, p,p] and B to the list [=,=° . 
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7 : Comparison of Terms 


7.15 on - membership of a list 
on (el, list) 
ARGUMENTS 
el : any term 
list : list or variable 
- DECLARATIVE READING 


el isan element on the list list 
DEFINITION 
The program cn is defined as ioliows: 


ortar IE 


eee 


ae 


- 
-+ 


7.16 Length - find the length of a list 


length (list, integer) 


ARGUMENTS 

jist : a list 

integer ; a variabie or an integer 
DECLARATIVE READING 


inceger is the iencth of the list iist 
USES 


To find or check the length of a list. | 
For example, the cal] 


will bind Z to 4. 
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7 : Comparison of Terms 


7.17 remove - remove an item from a list 


remove (item, list, remainder) 


ARGUMENTS 


item : any term 

list - variable or List 

remainder : vaniable or list 
DECLARATIVE READING 

remainder is the list List with the element item removed. 
EXAMPLES 
The call 


Vesave (S; §G,U; Spt; 24. D) 
will bind {to the list 10; urey]: 
The call 

esgor isn Lepae ape. ou 
will bind L tothe list [1,2Z2,2,4,5 
The cal} 


resove(E, !2;3;4]; L) 


will bind Z to 2 and L to '3,4]. On backtracking = will take the vaiues 2 and + wit the 
corresponding values of L being (2,4: and [2, 2°. 


The call 
remove (yr, TA Urti Sip D) 


-~ 


will fail. 
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7 : Comparison of Terms 


7.18 reverse - reverse a list 


reverse (list, revlist) 


ARGUMENTS 
list ` variable or list 
revlist : variable or list 
DECLARATIVE READING 


revlist isthe list list with the order of its elements reversed. 


EXAMPLES 
The call 


reverse ([p,&,7,7,S], 


will bind L to the list [$,2,27,4,P!- 
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8 Miscellaneous String Operations 
In MacPROLOG strings can be represented and manipulated as lists of single character atoms or as 
lists of bytes. A string in packed form is an atom. 


There is a primitive stringof that can be used to convert between atoms and lists of characters, 
in addition to the usual name which converts between atoms and lists of bytes. 


The primitive charof can be used to convert between single character atoms and their ASCII 
byte codes. 


Other string processing primitives are concat which joins the prt names of two simple terms 
together to form a new atom, and gers-7m which generates new atoms based on a c'ven root. 


Also provided are the primitives version, date and time which give access to ine cures 
version of MacPROLOG, and the current date and time expressed either numerically or as strings. 


8 : Miscellaneous String Operations 


§.1 stringof - converts between character lists and atoms 


stringof (chars, atom) 


ARGUMENTS 
chars : variable or list of characters or a list pattern 
atom : variable or atom 


chars can only be a variable or a list patrem (which may contain variables) if atom 1s an atom. 
tom can only be a variable if chars is a fully instantiated list of characters. 


DECLARATIVE READING 


chars 15 the list of characters of the atom 2212m. 





naracters | Of the second arcumen:. For exams, the call 
S22 TOOL Layee ee eyo! 


wii succeed 





3 > Produces a iis: of characters ‘rom an atom. In this use the second argument must be 
n atom at ine ume of evaluation. The firit 2r-gument is unified with the list of cheracters of the 
xom. If the empty atom “is given its list c: cnaracters is the empty list í}. 


ee noor (List red) 

results in List being bound to the list "=,:,¢,d], and 
evs anoaoel {Laistz; Ar] 

sinds Liszztothelist ['2', '*']. 


For the unpacking use, the first argumen: may also be a list pattern. This allows particular 
characters of the atom to be picked up as tne binding of variables in the iist pattern. 


E # Gh; © y Fred) Ch = È 
Seringor (l(t, $ICirSjy -22 = 
S221 nooi E: r|Chrs], 26 


3, Packing. This takes a list of characters and produces an atom from it. It is the inverse of the 
unpack use. 


stringof([f, ry €; dj, on) Con fred 
stringof([], Con) Con = ''! 


8 : Miscellaneous String Operations 


8.2 charof - converts between a single character atom 
and its ASCII code 


charof (char, code) 


ARGUMENTS 
char : single character atom, or variable (if code is not a variable) 
code ~ : integer, or variable (if char is not a variable). 
DECLARATIVE READING 


The character atom char has the numeric code code. The code is essentially ASCII except tha: 
where extra characters such as > ® f é are used the code is specific to the Macintosh (see the 
Appendices). 
USES 
1. Checking. If char is a single character atom and sce isan integer, charo= wiil succeed :: 
code is the character code for char. 
For example, the call 
charof ('A', 65) 
will succeed, but the call 
charof (a, 65) 
will fail. 
2. Finding the numeric code of a Character. If char is a single character atom and code 15 - 
variable, the latter will be bound to the code for cher. 
For example, the call 
charof (a, Code) 
will cause Code to be bound to 97. 
Note that is can also be used for this purpose. The cal 
Code is "a" 


will also bind Code to 97 because "a" is the list |27; comprising the integer byte code of = 


and is evaluates a list of a single integer to that integer. 
3. Finding the Character Represented by a particular Code. If cher is a variable. and code an 
integer, char will be bound to the character represented by the integer. 
For example, the call 
charof (Ch, 98) 


will bind Ch to the single character atom b. 
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8 : Miscellaneous String Operations 


8.3 name - convert between simple terms and strings represented as 
lists of ASCII codes. 


name (simple term, list_of bytes) 


ARGUMENTS 
simple term : an atom. number 
or a variable (if list_of bytes is nota variable) 
iist_of bytes : a list of integers which are byte codes, 
or a variable (if simple term is not a variable) 
DECLARATIVE READING 


pie simpie_term has an unquoted print name comprising the sequence of ASCII codes on 

list_of bytes. Remember that a list of bytes is the representation of a string term - a 
re of characters surrounded by double quote marks, such as "apple" (see the chapter on 
Syntax). 


USES 


generate or check alist s. Ifthe simple term argument is given, this 1s converted 
a a list of byte are of the vee that make up > the (unquoted) print name of the term, and 
this list of bytes is unified with list _of bytes. 
For exampie, the call: 


would result in the variable String being bound to the list [116,111,109] (which is the 
String "tor"). 


To conver: 2 list of bytes into an atom. Ifthe list _of_bytes argument is not a variable but 
a a of byte codes, and simple_ terr is an unbound variable, then list of bytes is 
compressed into an atom which becomes the value of simple_term. 
For example, the call 


name (Num, "azi") 


will result in Num being bound to the atom ‘223'. 
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8 : Miscellaneous String Operations 


8.4 concat - construct a new atom from two simple terms 


concat (siml, sim2, atom) 


ARGUMENTS 

simil : simple term ( atom, integer, floating point number or variable) 

sim2 : a simple term 

atom : a variable 
DECLARATIVE READING 
The atom atom comprises the print names of the :wo simple terms sim1 and sim2 appends: 
together. : f 
USE 


Only one mode of use is supported. Two simple :erms can be gived' together io forma rer 
atom. Normaily the terms to be glued together are atoms: for exemr-e the call 


would result in the variable X being bound to the atom fredaies. 

Another common use is to append digits to a basic stom as a form o7 symbol generaior: 
scanat (Label 23ra] 

results in ¥ being bound to the new atom labe1Z= 'but see ger.z.7 below). 

PRAGMATIC CONSIDERATIONS 


The limit of the size of a single atom is 255 characzers. If you iy 10 Construct a new atom sii 
more than 255 characters the extra trailing characters wiil simply te ignored. 
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8 : Miscellaneous String Operations 
8.5 gensym - generate the next symbol with a given root 
init _gensym - initialise the subscript count for a given root 


gensym(root, symbol) 
init _gensym(root) 


ARGUMENTS 

baronet! : an atom 

symbol  :avamable (wil be bound to an atom) 
SIDE EFFECTS 


The gens+7. call binds the symbol vanabie to the next atom in the sequence 


Zach cali tc rensymreturns the next atom in the sequence for its roct Starting at rooete and 2: 
wae Same tone: ik anererme=.s. the intese subscript to be used for the next cail. A cali ti 
bee eee Cr Ne Senet oct will reinidalise the su osenpt to 0. 

ie ea) Sze ator os cae DS cenena 1s 255 Characcers. 

There is cnis one supported use for these ommiltives: to return the next symbol for a given = ne oe 


"e w 


we ur 


with gers, and to reinitialise the sequence of symbol names for a given roci with 


=xample secuence of uses: 


csensym(level,Syml) /* Symi is bound to atom level0O */ 
sensym(leve_, Sym2) /* Sym2 is bound to atom leveli */ 
init-gensyr /ievel) /* reiniualise subscnpt count for root level */ 
censym(leve_, Sym3) /* Symz is bound to atom level */ 
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8 : Miscellaneous String Operations 


8.6 pname - find the print name of a term 


pname (term, name) 


ARGUMENTS 

term : any term 

name : a variable or atom 
USE 


This primitive converts between a Prolog term and the atom representing its print name. 
For example, the call 


pname (foo(a,1+2),%) 
will bind X to the atom 'foo(a,1+2)'. 
The calls 


Aa Spaga (289, Y) f 
pzame (Y, Z). 


will bind Z to the atom '17'. 


8.7 version - find the current version of MacPROLOG 


version(vers) 


ARGUMENTS 


rg- ‘ vanable 


RY 


LSE 


This primitive returns an atom which gives informa::on on the version of MacYROLOG mise 
The call 


version (X) 
will bind +: to an atom similar to the following: 


'-2A MacPRCLOG™ Version 2. 


©) 
| en 
KO 
CO 
~] 
l i 
trj 
ti 
{4 
ct 

{2 
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8 : Miscellaneous String Operations 


8.8 date - find current date, or check date 


date (year, month, day) 
date (year, month, day, strdate) 


ARGUMENTS 
year : variable or integer 
month : variable or integer 
day : variable or integer 


Strdate : variable 
USE 
|. Three argument form 
L all three arguments are variables, this primitive returns the current date as three integers. 


I: all three arguments are integers, the call checks that these integers represent a valid date (for 


example it checks that mon< + is an integer between 1 and 12, etc.). Any date may be given - there 
1s no check that it is the current date. 


* 


2. our argument form 
Tne final st rdate argument must be a vari2ble. 
E the first three arguments are all variables. tne current date is returned as in the three argumen: 
form, and 1s aiso returned as an atom in strate. 
E tne first three arguments are all integers. tne date 1s converted to string form and returned as an 
ziom in strdate. Note that 1900 is subtracted from the year on conversion, so that dates before 
1900 will yield strange results! 
EXAMPLES 
If the current date is July 11th, 1987, then the call 
aate (Y,M,D) 
will bind Y to 1987,Mto7 and D to 11. 
The call 
Gate (1956;.2;25,)) 
will bind D to the atom 
Tath March 22° 
The call 
date (1987, 4, 22) 
will fail. 


70 


8 : Miscellaneous String Operations 


8.9 time - find current time, or check time 


time (hours, mins, secs) 
time (hours, mins, secs, strtime) 


ARGUMENTS 
hours : variable or integer 
mins : variable or integer 
secs : variable or integer 


strtime : variable 
USE 
|. Three argument form 
If all three arguments are variables, this primitive returns the current time as three integers. 


If all three arguments are integers, the call checks that these integers represent a valid time (for 


example it checks that mins is an integer between 0 and 59, etc.). Anv time may be given - there ‘s 
no check that it is the current time. 


2. Four argument fom 
The final s¢rtime argument must be a variable. 


If the first three arguments are all variables, the current time 1s retumed as in the three argument 
form, and is also returned as an atom in strtime. 


* 


If the first three arguments are all integers, the time 1s converted to string form and returned as ṣi 
atom in strtime. (The secs value is not included in this string form.) 


EXAMPLES 
If the current time is 3:20:11 pm, then the call 
“ime (H,M,S) 
will bind £ to 15, Mto 20 and S to 11. 
The call 
=sme(18;, 5-30; 2) 
will bind 7 to the atom 
'6.Q5pm' 
The call 
time (19,4, 62) 


will fail. 
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9 Data Base Primitives 


The usual Edinburgh interpreted data base primitives assert and clause have been generalised 
in MacPROLOG to allow for the storing and retrieval of ground clauses - clauses containing atoms 
which are specified to be variable names. In fact, all MacPROLOG interpreted clauses are stored as 
ground clauses with an associated list of variable names. If a hollow clause - a clause containing 
variables - is added to the data base the variables are given unique underscore names and these are 
stored as the associated variable names. 


There are also additional primitives asserzx and clausex which allow storing and retrieval of 
either hollow or ground clauses at specified positions in the list of clauses for a relation. 


The ability to store ground clauses. combined with the ground read and ground to hollow 
conversion primitives, is what allows MacPROLOG to remember user variable names in interpreted 
clauses. It also allows you to build applications in which entered variable names are remembered. 
You can even build applications which use 2 cuite different variable name convention, for example 
=aving as Variable names oniy those atom: that begin with any or some. Ail you need is a 
crocram to extract the list of the atoms that ere the application variable names in a read-in ground 
raem. You can then use tcc low to conver: it into a hollow term, with just these atoms replaced 
av variables. Alternatively. if the read-in term represents a fact or rule you can compile it into 4 
~ipyse term end store it with the extracted lis: of atoms as its associated variable names. When the 
~ause is used in an evaluatior.. or retrievec using clause, these names will automatically be 


+ 
4 


reviaced by variables. 


Vou can initalise the interpreted data base with the clauses produced by compiling the program text 
c7 one or more Interpreted or Data program windows. The text of a Data window will be updated 
:? the definition of any of its relations is changed using a data base primitive. The text of an 
interpreted window will not be changed when the interpreted data base is changed. You can also 
‘ritialise the interpreted data base using the consult primitive - see below. 


Tne clauses of the interpreted Gata base are actually compiled. However, each clause for a relation 
:s compiled independently, which is why the relation definition can be updated using assert and 
-e-ract. The clauses are also not fully compiled. Information is left in the compiled code so that 
thev can be reverse compiled, enabling clause and listing to be implemented. 


Because the clauses are compiled, dynamic is probably a better name for the MacPROLOG clause 
¿ata base. We use the name interpreted because the ability to retrieve the source term using 
~2ause enables interpreters to be written. I: is why full tracing is possible for relations defined in 
Data or Interpreted windows. 


Code generated for Compiled and Optimised windows is produced by compiling all the clauses for 
a relation at the same time. Consequently it is not dynamic: it cannot be updated by adding and 
deleting individual clauses. Moreover, the code generated cannot be reverse compiled, so the 
clause primitive cannot be used. Code gensrated from Compiled and Optimised windows is fully 
compiled code. 


9 : Data Base Primitives 


You should not try to add clauses for a fully compiled relation. If you do, even if you are adding a 
clause with a different arity than that of the existing compiled definition, you will get an error 
message "Adding clause for a compiled relation" (error 14). This 1s because MacPROLOG does 
not distinguish between different arities for a relation name. This 1s also the reason why all the 
clauses defining a particular relation must be in a single edit window. 


The save primitive can be used to save all the clauses of the interpreted data base in source form in 


a file. The csave primitive can be used to save all the compiled code - the code for both compiled 
and interpreted programs - in a file. 


You can get rid of a fully compiled definition, or al! the interpreted clauses for a given relation 
name, using the kill primitive. 


The primitives def, ide#, cdef and sdef provide tests for defined relations, and the four 


dictionary relations dict, idict, cdict and sdicz allow you to find the names of all the 
defined relations. 
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9 : Data Base Primitives 


9.1 assert Orassertz -add a new last clause 


assert (clause) 
assert (¢gclause, varnames) 


ARGUMENTS 
clause : term, a valid clause 
gclause : ground term, a valid clause 


varnames any list of atoms, specifying the variable names of gclause 


USES 


1, Single argument call. This adds clause as a new last clause for the relation name of the head 
of the clause to the interpreted data base. All the existing clauses remain. The variables in clause 

e given unique underscore names and the clause is added to the data base with these underscore 
names as the associated list of variable names. clause should not contain any (quoted) atoms 


beginning with underscore. 

2. Two argument call. Adds ccolause as anew last clause for the relation name of the head of the 
Clause to the interpreted data base. gclause must be a variable free (ground) clause. The 
vérnames list of atoms is stored as the associated list of variable names for the clause. 

Usually gciause and vernames will have been returned by some call of greac or 
rrompt_greadora ground read from a dialogue field, but they can also be constructed by some 
arbitrary MacPROLOG evaluation. The variabie names do not need to be Edinburgh syntax variabie 
names. 

Example use: 


assert ( (likes (xeith,any person) :- 


will add the clause 
likes (keith,any person) :- Likes (any person, logic) 
with any_pezson as the only associated variable name. 
The cal] 
assert (likes (pooh,honey) ) 
will add the assertion 
likes (pooh, honey) 
with no associated variable names. 


assertz is an accepted synonym for assert. For either use the call fails if the clause argument 
is not a valid Edinburgh syntax clause. 


ERRORS 


Invalid form of use error will be signalled for the two argument call if gclause is not ground or 
varnames is not a list of atoms. It will also be signalled for the one argument use if clause 
contains any (quoted) atoms beginning with underscore. 
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9 : Data Base Primitives 


9.2 asserta - add a clause at beginning of current list of clauses 


asserta (clause) 
asserta(gclause, varnames) 


ARGUMENTS 


clause : term, a valid clause 
gclause : ground term, a valid clause 
varnames :any list of atoms, specifying the variable names of gclause 


USES 


The same two uses as asser- except that the clause is added at the beginning of the current list of 
clauses for its head relation. 


ERRORS 


Same as for assert. 


9.3 assertx - add a clause at a specified position 


assertx (clause, index) 
assertx(gclause, varnames, index) 


ARGUMENTS 
clause : term. a valid clause 
gcolatse : ground term, a valid clause 
varnames ‘any list of atoms, specifying the variable names of gclause 
index : integer 
USES 


current list of clauses for its head relation. 

Clauses for a relation are indexed starting at 1, so that 
asserix(clause, -) 

is equivalent to 
asserzta(clausé) 


If index is greater than the number of clauses for the relation, the new clause is added at the end 
of the hist. 


ERRORS 


Same as for assert. 
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9 : Data Base Primitives 


9.4 clause - retrieve a matching clause body 


clause (head, body) 
clause (ghead, gbody, vars) 


ARGUMENTS 

head : a calì term 

ghead : a call term 

body : variable, or a term denoting the body of a clause 

gbody : variable, or a term denoting the body of a clause 

vars : variable, will be bound to a list of atoms, the variable names of the clause 
ESE 


1. Two argument call A search is made for the first hollow copy of an interpreted data base clause 
for the relation name of head with a head and body that unifies with head and body. Variables 
in keadand body will be instanuated by tne match. The hollow copy of a data base clause is mace 
by replacing each atom of the associated list of variable names by a new unique vanable. 


An empty body is designated pv the atom trus. 


O- packtracking, the next ma:ching clause will be found. The call fails when there are no oiner 
maiching clauses. 


2. Three arsument call Similar to the two argument call, except that ghead and gbody are 
unified witn the head and body of a ground copy of the data base clause. In the ground copy the 
variable names are left as atoms. The vars hist of atoms is the associated list of variable names for 
tne matching ground clause. 
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9 : Data Base Primitives 


9.5 clausex - retrieve a matching clause body from a position 


clausex (head, body, from, index) 
clausex (ghead, gbody, vars, from, index) 


ARGUMENTS 
head : any term which denotes a relation call 
ghead -- Dany term which denotes a relation call 
body : variable, or a term denoting the body of a clause 
gbody : variable, or a term denoting the body of a clause 
from : integer, the clause to search from 
index : integer or variable, the position of the matching clause 
vars : variable 

USES 


This has the same uses as clause, except that the search starts at the “rom'th clause in the list ci 
Clauses for the relation name of the head term. If from is 1 the search starts at the firs: clause. 
£ 


ait Se 


If the index argument is a variable it will become tze actual position of the matching clause 


á w wee 


rede d de TO dk e 
retrieved. 


If the index argument is an integer, this must be the same value as Sem Ane Oni Ci St awe 


the index th position will be matched with zheac end 


1. 


T 
= = tr 
~~ hk 


rr 
_ 
- 


In the four arcument call, head and S773 are moicnted ugainst hoiiow copies of the data buse 
a] 
C dUSES. 


In the five arcument call. ghsad and 75c Jy are maicned against a ground cone. and sro 


becomes the list of vanable namés of the matched Clause, 
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9 : Data Base Primitives 


9.6 retract - delete a matching clause 

retract (clause) 
ARGUMENTS 

clause : term, a clause pattern 
USE 
If there is a matching clause in the data base, that clause is deleted and any variables in clause are 
instantiated by the match. On backtracking there is an attempt to find another matching clause. The 
search always starts at the beginning of the list of clauses for the relation name of clause. Soall 
clauses asserted between the retract and the redo of the call, even if added using asserta, are 
candidates for deletion on the redo. The call fails when there is no matching clause. 
If clause is nota valid clause pattern the call fails. 


For example, if the data base contains the clauses 


likes (keith, Somesne) :-.ikes (Someone, logic) 
and likes (pooh, hcney} 


then the call 
retract ( (likes (2,3) :-C)) 

will firstly retract the first of the above clauses, and 
A will be bound to keith 


B will be an unbound variable, for example 1234 
C will be bound to Likes (2234, logic) 


On backtracking, the second clause will be retracted, and 
A will be bound to rooh 
B will be bound to honey 
C will be bound to =rue 
9.7 retractx - delete a clause at a specified position 


retractx (name, index) 


ARGUMENTS 
name : atom, name of an interpreted data base relation 
index : Integer 

USE 


The index'th clause for the relation name is deleted. If index is 1, the first clause is deleted. 
On backtracking there is no attempt to redo the call. 
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9.8 retractall - delete all the matching clauses 
retractall (clause) 
ARGUMENT 


clause : term, a clause pattern 


USE 


All the clauses in the interpreted data base which match clause are deleted in one operation. 
Varjables in clause are left uninstantiated by the call. On backtracking there is no attempt to redo 


the call, even though matching clauses may have been asserted. If clause is not a valid clause 
pattern the call fails. 


9.9 abolish - delete all interpreted data base clauses for a relation 
that have a given arity 


abolish(name,arity) 


ARGUMENTS 
nare : atom, name of an interpreted cata base relation 
arit? : non-negative integer 

LSE 


All the interpreted data base clauses for relauon nams with arity head arguments are deleted in 
one operation. On backtracking there is no attempt to reco the call. 


9.10 kill- delete one or more complete relation definitions 
kill (reis) 

ARGUMENT 
rels : atom, or list of atoms 

USE : 


The complete definition, whether interpreted or compiled, for each relation name in rels 1s 
deleted. Any atom which is not a relation name is ignored. This is the only way to get rid of a 
compiled definition. 
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9.11 save-save interpreted programs as text 


save (file) 
save (file, vol) 
save (file, vol, rels) 


ARGUMENTS 

file : atom, name of a file 

vol : integer, volume identifier 

rels : list of atoms, names of interpreted relations 
USES 


1. One and rwo argument calls. Saves all the clauses of the current state of the interpreted data base 
in source form in a text file ile. This is on volume vol if this argument is given, otherwise it is 
on the current default volume as recorded by dvol. Any existing file on the volume of the same 
name is overwritten. 


2. Three argument call. Saves all the clauses for the given list of intepreted relations in the file 
file on volume vol. 


9.12 csave -save compiled code 


csave (file) 
esave (file,vol) 
csave (file,vol,rels) 


ARGUMENTS 

file : atom, name of a file 

vol : integer, volume identifier 

rels : list of atoms, names of relations 
USES 


1. One and two argument calls. Saves all the compiled code of all the currently defined user 
relations (i.e. all the relations returned by dict) in a code file file. This is on volume vol if 
this argument is given, otherwise it is on the current default volume as recorded by dvol. Any 
existing file on the volume of the same name is overwritten. The saved definitions can be reloaded 


using the consult primitive or the Load... command of the programming environment. 
Note that the compiled code of all the clauses in the interpreted data base is also saved by this call. 
2. Three argument call. Saves all the compiled code for the definitions of the relations in the list 


: rels in file file on volume vol. The rels list can be a mixture of compiled and interpreted 
relations. 
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9.13 consult -load a program froma file 


consult (file) 
consult (file, vol) 


ARGUMENTS 

file : atom, name of a file 

vol : integer, volume identifier 
USE 


Load a program from a file. The file can be: 


(1) a compiled code file - the code is loaded, overwriting any existing compiled or 
interpreted definitions for relations with the same names as in the lozčed file. So for a compilec 
code file this is actually a reconsult. Previously saved code for interpreted relations in the file 1s 
put into the interpreted data base. 

(2) a text file of clauses - no edit windows gre created but ell the clauses in the file are 
added to the interpreted data base, using assert, as they are loaGec. They are therefore added to 
the clauses for existing interpreted data base relations of the same name. Variable names in the 
read-in clauses are remembered. 


ERRORS 


When loading a text file the error ‘Cannot add clause for compiled reiaton’ (error 14) is signailed i: 
a clause is encountered for a relation which has a compiled definition. i: you choose the Succeed 


response, the load will continue but the clause will be ignored. Any czher response will cause the 
load to terminate. 


914 xrefs -find the list of relation names used in a program 


xrefs(rel_name, list_of_ relations) 


ARGUMENT 
rel name : atom, name of a reiation 
Ilise of relacions : variable 
USE 
The variable list of relations willbe bound toa list of all che names of the relations mu: 


appear in the program for r2l_name. A relation name will be included on the list even if i! 
appears in an argument term of a call in the program. 


This can be used for compiled programs as well as interpreted programs. 
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9.15 def -testifa relation is defined 
def (call) 

ARGUMENT 
call : call term 

USE 


To test if an atom is the name of a relation defined by either a compiled or interpreted program, or 
to test if a compound term has a functor which is a defined relation name. 


9,16 ide -test ifa relation is interpretively defined 


idef(call 


AR Uv. T 
a Cal rrm 
Tee 
Le ae 
Te test i an atom is the name of a rela:ion defined by an interpreted program. or to test if g 
compound term has a functor which is a interpreted relation name. 


C17 cac£-testifa relation is defined by a fully compiled program 
cdef (call) 

ARGUMENT 
call : call term 

LSE 


To test if an atom is the name of a relation defined by a fully compiled program, or to test if 2 
compound term has a functor which is the name of a fully compiled relation. 


9.18  sde£- check ifa relation is defined by a system program 
sdef (call) 
ARGUMENT 
call : call term 
USE 
To test if an atom is a protected relation name defined by a system program (its name is in the 


system dictionary), or to test if a compound term has a functor which 1s in the system defined 
relations. 
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919 dict -find the list of all the user defined relations 


dict (list) 


ARGUMENT 
list : variable, will be bound to a list of atoms 
USE 


A list of names of all the relations defined, either by clauses in the interpreted data base or by fully 
compiled code, is returned as the binding for list. s-ct retums the list of all the names for 
which de f 1s true. 


9.20  idict -find the list of all the user defined interpreted relations 


idict (list) 
ARGUMENT 

list : variable, will be bound to a list of atoms 
USE 


A list of names of all the relations defined in the intergreteċ data base is returned as the binding fe: 


ist. idict retums the list of all the names for whicn Lief is tee: 


921 edict. find the list of all the user defined compiied relations 


eaict (iist) 


ARGUMENT 
aes > yortuble. wiil be bound to a ist 77 atoms 
eyo 
a list of names of all tie fully compiled relations ©: returmec us one Sp TOR ce ee 
-eturns the ist of all the nemes for which oder 1s tee. 


9,22 sdict - find the list of reserved system relation names 
sdict (list) 
ARGUMENT 
liet : variable, will be bound to a list of atoms 
USE 


Retums the list of all the protected relation names. You are not allowed to enter a definiuon for any 
relation name on the sdict list. 
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9 : Data Base Primitives 
9.23 listing - list a relation 
listing 
listing (pred) 
ARGUMENTS 
pred : atom or list of relation names 


USE 


In the no argument call, al] interpreted relations currently defined are listed to the current Output 
channel. 


If the prec argument is given. the specified relation or list of relations are listed to the current 
Output channel. 
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10 Property Management 


In addition to the interpreted data base which can be manipulated using the database primitives. 
MacPROLOG has a property management system similar to that of LISP. With any atom, we can 
associate any number of properties each of which has a value which can be any term. Any atom or 
number can be used as a property name. Properties can have their values set, changed anc 
retrieved. MacPROLOG's programming environment makes heavy use of properties. For 
example, the identity of the edit window in which a relation rel is defined is recorded as the value 
of the property 'DEFINWIN' of the name rel. 


In addition to the property manipulation primitives there are two very useful property search 
primitives. One, get_cons, enables you to find all the atoms which have an associated property. 
the other, zez props, enables you to get all the names of properties associated with a giver 
atom. 


The advantages of using properties instead of facts in <2 interpretec cata base are compactness a 
the representation of the atom property name .s-78 triples, increased speed ci retneval c: 
the property values, and the fact that you can find the -zmes of all the croperties of an 2:om. 

The disadvantage is lack of symmetry between the iiom name anc the property tace AC 
record the value V of a property P for an atom A as 2 <.2zse for the re-ation P, then you can retre» 
A given V. or you can remieve V given A. If you reccre it as the vaiue of property P fcr the aez 
A, then you cannot retrieve A given V, you can oniy zemeve V given A. 


Finally, the four primitives remember, recs... ʻe 
features of a symbolically named memory location. 


t+, 


Å- = — r {L “ite ad ‘aa 
ait = and forset rovid iss 
-r a 


Reserved property names 


In the Appendices is a list of the property names usec 2} MacPROLOG: you should not use anv 7: 
them as a property name. If vou use them for your own rroperties you may affect the ara LLE 3 
a MacPROLOG primitive or a menu command of :ze programming environment. The reserves 
names ail use capital letters, so you will avoid a ciasn :t vou use oniy lower Case teters as yent 
property names. A property name can be any atom. 


10 : Property Management 


10.1 set _prop -seta property value 


set_prop(object, property, value) 


ARGUMENTS 
object : atom 
property : atom or integer 
vazuse ‘any term 
SIDE-EFFECT 


value becomes the remembered value of the property property of the object chject. Any 
previously remembered vaize of the preverty of objectis lost. 


10.2 get _prop -retrieve the value of a property 


get_prop(object, property, value) 


ARGUMENTS 
ofiect > aiom 
property : atom or intege 
Vaus : any term 

USE 


The current value of the property property of object object is retrieved and unified with 
val Ve. 
If there is no remembered value, the call fails. 


10.3 cdel_prop -remove a property value 


del _ prop(object, property) 


ARGUMENTS 
object : atom 
property : atom or integer 
SIDE EFFECT 


The remembered property value of object is forgotten. A subsequent call to 
get_prop(cbject, property, value) 
will fail. 


del prop does nothing and succeeds if there is no such object or property. 
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10.4 remember -store a value 


remember (atom, value) 


ARGUMENTS 
atom : an atom 
value : any term 
USE 


Stores value as the currently stored value of atom. Any previousiv assigned value is lost. 


10.5 recall -retrieve a stored value 


recall (atom, value) 


ARGUMENTS 
ACEN : an atom 
value : variable or term 
USE 
The currently stored value of atomis retrieved and unitied with váli. 


recall fails if atom has no currently stored value. 


10.6 default - retrieve a value or a default 


default (atom, value, default) 


ARGUMENTS 
eei : an atom 
Tous : any term 
asfauit : any term 
USE 


value will be unified with the curently stored value of azon. if there is one. k wil be unified 
with defau_t if there is no currently stored value. 
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10.7 forget - delete a stored value 


forget (ator) 
ARGUMENT 

atom : an atom 
USE 


To delete the stored value associated with a-om. A recall on ator will now fail. 
A call to forget always succeeds, even if there is no stored value. 


10.8  get_cons -find all the objects witha given property 


get cons (property, list) 


ARGUMENTS 
Gnomes y : atom or integer, name of a property 
262 ‘unbound vanadie 

Lae 


19.9 get props -finc all the properties of a given object 


get _props(object,list) 


ARGUMENTS 

obiect : atom 

Iret : unbound variable 
USE 


The variabie list will be bound to the list of all the names of the properties currently associated 
with object. 
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11 File and Window I/O 


The usual Edinburgh term and byte I/O primitives are available for use in MacPROLOG programs 
as well as an extra term input primitive gread. They can be used for file YO, window I/O and 


serial I/O. Windows may be of type prog, disxc or info (see the chapter on Window 
Handling). 


As usual, the input / output channel can be set with a call to see or tell. However, as an 
alternative, MacPROLOG allows the name of the file or window to be used for a particular I/O 
operation to be specified in the I/O call. This allows an application to read and write to severai 
windows or files without the need to repeatedly switch channels. If an I/O operation is to be 
performed on a file using the explicit file name feature, the file must first be opened using an oper. 
call. If the channel is printer or mc¢enm, it should first be opened and configured by calls to 
seropen and serconfig (see the chapter on Serial L'O). 


You can write to the Default Output Window by giving the reserved window name user. 
In fact, user is the default channel to which output is sentif no channel is given as an argument to 
the output call and no other default output channel has been specified by atell cai. 


To read from the keyboard, you should use the crcmpt reac, crompt gread or asx 


-~ 


primitives described in the chapter on Predefined Dialogues, which ailow a prompt to be displayed. 
However, if you use read or gread with user as the current input channel, a similar standarc 
input dialogue will be displayed with the default prompt: "Enter any term:". 


11.1 see - set the input channel 
see (channel) 
ARGUMENTS 
channel _ : file or window name 
USE 
The default input stream 1s set to channel. 
If an input channel is not set. user is assumed. 


With user as the input channel only the single argument calls to esa and creac will succeed. 
Single argument calls to get, get O and skip will all immediately rau. 


If channel is a file that is not already open, an attempt will be made to open a file of the given 
name on the current default volume (see dvo1). If the file is already open, calls to see will not 
reopen it or reposition the file pointer. 
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11.2 tell - sets the output channel 


tell (channel) 4 g 
tell (channel, volume) v `. ae ak n A 
ARGUMENTS 
channel :file or window name 
volume integer, volume icenafier 
USE 
The default output stream 1s set to Channe-. 
lf channel is a file name. an optiona! vziume id can be given. If it is not, the current default 


volume (see avol} will be assumed. 
lf the channel is a file which is not alreecv open, a file of the given name will be created. If the 


file is already open, the cali will not recrea:z ine file or reposition the file pointer. 


X an output channel is not set. user is assumed. 
With usez as the output channel, outpu: wil be sent to the Default Output Window. 


H:s seeing - finds the input channel 
seeing (channel) 
ARGUMENTS 


“hannel :vanebpie 


Q 
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bound to the file or window zame of the current default input channel. 


11.4 telling - finds the output channel 
telling (channel) 
ARGUMENTS | 
channel : variable 


USE 


channel is bound to the file or window name of the current default output channel. 
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11.5 seen - cancel default input channel selection 


seen 


USE 
This cancels the effect of the last see call - user becomes the current input channel. 


If the last input channel was a file, the seen primitive will automatically close the file. 


11.6 told - cancel default output channel selection 
told 
USE 
This call cancels the effect of the last tei1 call - user becomes the current default output channe:. 


If the last output channel was a file, the told primitive will automatically close the file. 
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11.7 read - read a hollow term from an input channel 


read(term) 
read(channel, term) 


ARGUMENTS 


term : variable or term 
channel : atom, name of channel 


USES 


If term is a variable, it will be bound to the next term on channel. The term must be terminated 
by a full stop followed by space or a carriage return, which will be consumed by the call. Any 
vanable names in the read-in term are converted into variables. 


If the term argument is not a variable, an attempt is made to unify the read-in term with terr. 
The call fails if the unification fails. 


For the single argument cali. if user is the current default input channel, the following modeless 
dialogue vill be displayed 





A term should be entered in the edit field of the dialogue. No terminating full stop is required in this 
case. 

When the end of the file or the end of the window is firs: reached, term is unified with the atom 
end of file. Subsecuen: calls to rs223 will procuce the error "Read past end of file or 
window". If this is signatie¢ vou should select the Stop or Fail response to the error handier 
dialogu 

Gl ogue, 


Note that a read takes place at the current position in channel. For a window, this is the cursor 
position, and for a file it is the file pointer. The position is updated after the read. See the 
cursor primitive in the chapter on Window Handling and the seek primitive in the chapter on 
File Handling for more information on positioning these file and window pointers. 
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11.8 gread - read a ground term from an input channel 


gread (term) 
gread (channel, term) 
gread (channel, term, varnames) 


ARGUMENTS 

term : variable 

varnames : variable 

channel : atom, name of channel 
USES 


This call is similar to reac, but the difference between zreac and read is that variable names :7 
the read-in term will not be converted into variables. They will appear in term as (quoted) atoms. 


Where the varnames argument is given, this will be d0und to the ‘ist of atoms that are the variate 
names of the read-in term. 


PRAGMATICS 

See the description of prompt _gread for an illustration of the usefulness of such a ground reli 
primitive. In can be used in conjunction with the iwo argument ‘orm of assert to remene: 
variables of read-in clauses stored in the interpreted c2:2 base. 


11.9 edintok - read a single token from an input channel 


edintok (token, type) 
edintok (channel, token, tyre) 


ARGUMENTS 
toxen : variable 
t.ce : variable 
channel -atom. name of ¢nannel 
USE 
A single token is read from the current input channel. or from channel if this argument: :s 
given. 


The type of the token is an integer, indicating one ci the following. 


Separator (space or dot space: 

Punctuation character 

Single character symbol (e.g. : or .’) 

Symbolic name (e.g. £££) 

Variable (alphanumeric, starting with uppercase letter or underscore) 
Alphanumeric atom 

Number 

String 

Quoted atom 


CO~I A BW tO © 
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11.10 write- write an operator term to an output channel 


write (term) 
write (channel, term) 


ARGUMENTS 

term : any term 

channel ‘atom, name of channel 
USE 


If the channel argument is not given, terr is written out to the current default output channel, 


Variables are displayed as underscore names. 
Atoms that would need to be quoted on input are nor quoted. 


Current operator declarations are used. 


11.11 display - write a term to output channel ignoring operators 


display (term) 
display (channel, term) 


ARGUMENTS 
term : any term 
channel atom. name of channe! 


CSE 


If channe2 is not given, term is written out to the current default output channel, otherwise it 1s 
sent to channel. 


Variables are displayed as underscore names. 

Atoms that would need to be quoted on input are quoted. 

Operator deciarations are ignored. 

PRAGMATICS 

Use this primitive when saving terms to a text file which you will not want to edit. When you read 


the terms back, input will be faster if you used display rather than writeq to write the terms, 
because of the absence of operators. 
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11.12 writeq - write a quoted term to an output channel 


writeg (term) 
writegq(channel, term) 
writeq(channel, term, varnames) 


ARGUMENTS 
term : any term 
channel : atom, name of file or window 
varnames : list of atoms 

USE 


If channel isnot given, term is written out to the current default output channel, otherwise 1t is 
sent to channel. l 


Variables are displayed as_hex where hex is a hexacecimal number. 


Atoms that would be quoted on input are quoted with the exception that, in the three argument sae 
none of the variable names in varnames will be quoted. 


Operator declarations are used. 


Use the three argument form to display ground data base clauses that have been retneved using .n2 
three argument form of clause. 


11.13 nl - write a carriage return to an output channel 


ni 
nl (channel) 


ARGUMENT 
channel atom, name of channel 
USE 


For the no argument call, a carriage return character ‘ASCH 13) is sent to the current default outr.:: 
channel. If channel is given, it is sent there. 
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11.14 geto - get next character from input channel 


get0O (byte) 
get0 (channel, byte) 


ARGUMENTS 


byte : variable or integer 
channel :atom. name of channel 


USE 
If byte is a variable, it will be bound to the ASCII code of the next character on the current 
default input channel if no channel is given. or to the code of the next character on channel. The 


file pointer or window cursor will be moved forward one character. 


If the byte argument is an integer, the read-in byte is unified with the given byte. The call fails if 
the unification fails. 


The call fails if the input channel is user. 


11.18 get - get next printable character from an input channel 


get (byte) 
get (channel, byte) 


ARGUMENTS 


byte : variable or integer 
Channel :atom, name of channel 


CSE 
In the one argument call, byze will be unified with the ASCH code of the next printable character 
on the crrrent default input channel. In the two argument call, it is the code of the next printable 


character in channel. 


The file pointer or window cursor will be moved forward. Non-printable characters with ASCI 
code < 32 are skipped. 


The call fails if the input channel is user. 
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11.16 skip - skip to a character in a channel 


skip (byte) 
skip (channel, byte) 


ARGUMENTS 


byte : integer ASCII code 
channel ‘atom, name of channel 


USE 


The file pointer or window cursor will be moved forward to immediately after the next character 
with ASCII code byte in the current default input channel if channel is not given, otherwise the 
forward skip is in channel. 

The byte argument can be an arithmetic expression which evaluates to an integer in the ASCII 
range. This means that it can be also string of the form "o" where c is the character to be found. 
For example, 


sx ip ( "w. “n ) 
will cause a skip to immediately after the next occurrence of the full stop character. (The string 
"u js the list [46] comprising the code of a full stop, and as an arithmetic expression the unit list 


'46) evaluates to 46.) 
The call fails if the input channel is user. 


11.17 put - write a character to an output channel 


put (byte) 
put (channel, byte) 


ARGUMENTS 


byte : integer ASCII code 
channel :atom. name of channel 


LSE 


Puts character with ASCII code byte to channe-. or to the current default output channel if the 


-hannel argument is not given. As with skip, byte can be an integer expression. 


11.18 tab - write spaces to an output channel 


tab(int) 
tab (channel, int) 


ARGUMENTS 


int : integer 
hannel :atom, name of channel 


USE 
int spaces are written to channel, or to the current default output channel if this argument 1s not 


given. 
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11.19  tload -load a text file into a display window 


tload (file) 

tload (file, volume) 
ARGUMENTS 

file : atom. name of a text file 

volume : integer. volume ID 
USE 


An invisible display window with the name file is created, into which the text of file is then 


L the volume argument is not given the fiie is searched for in the default volume. 
If vou subsequently want to make the display window visible and bring it to the front you can make 
calls to wshow and wfronz after calling = sad. The window is for display only and cannot be 
edited. 
For example, the calls 

tload('8 Queens Help'), 

wshow('8 Queens Helc'), 

4 


wiront('8 Queens Heir 


will load the text file "8 Gueens Heis' mtoadisplay window of the same name, and will then 
make this window visible and bring it to the front. 
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12 File Handling 


In this chapter we describe the facilities available within MacPROLOG for using the Macintosh file 
system. We concentrate on those primitives needed to access the file system; the primitives which 
perform the actual input/output are described in the chapter on File and Window I/O. 


There are a number of special primitives which invoke standard Macintosh dialogues to select the 
file to read or write. These allow the programmer to construct MacPROLOG applications which 
conform to the Macintosh user guidelines. 


12.1 old - allow the user to select a file name and volume 


old(type, file, volume) 


ARGUMENTS 
type : a file type. It is an atom of up to 4 letters. 
Pee : variable. Will be the selected file name 


volume 1 variable. Will be the selected volume id. 
USE 


A standard file dialogue is displayed on the screen. All the files that are in the current folder witr 
the required type will be displayed. The user can change disks and open and close folders viz 
options in the dialogue. 


When the user has selected a file to open. the old primitive returns with the name of the Heats 
the integer identifier of the file's volume. 


The returned file and vciume values can then be used by the programmer to actually coer. ine 
file (see below). 


The old primitive fails if the user clicks on the Canc el button on the file diaiogue. 
PRAGMATICS 


The primary use for the ca primitive is for a program. io esiadiisn which files the user wisnes i1 
srocess. By specifying the required type the program ensures inat oniy those ies Wits 
relevant to the program are ever displayed on the screen: this recuces ihe clutter that the user has 13 
go through. The file types used by MacPROLGG are: 


'TOXT' : standard text file 

'SIGM' : MacPROLOG compiled code file 
'DROL' : MacPROLOG source windows file 
'>RBT' :MacPROLOG BOOT file 


To display all file types use the empty string " for the zyse argument. 


NOTE It is highly recommended that old be used for selecting file names and volumes. The main 
benefit of using the old primitive 1s that users are never asked to actually type in the name of aa 
existing file: they simply select the file they want from those which are available. It is also the oniy 
way to find the volume identifier which is needed in the open command if the file to be opened is 
not in the current default volume. 
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12.2 new - allow the user to create a new file name and select a volume. 


new (file, vol,prompt) 


ARGUMENTS 
file - variable. Becomes an atom which is the name of the file. 
vol - variable. Becomes the volume id on which to create the file. 


prompt atom. A message saying what sort of file is to be made. 
USE 


A standard file dialogue is dispiayed in which the user is invited to enter a new file name in an ecit 
field. The prompt string 1s displaved to inform the user what sort of file is to be created. 


Tre user has the opportunity to format disks or change disks and folders as well as to enter the file 


nome. If the file already exists then the user is asked to confirm that the old file is to be replaced. 

a5 of tne dialogue i. preloaded with tne name of the previous file that was selected usin? 
ool] to pa or new. This allows az application to use c-¢ to offer the user a menu c? 
n mav be consules. anc then to use new to allow the user to give a file name into Mice 
hongec dan is to ce saved. The Gefzult is the name of the file that was last consulted. 
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rimitive the user has the opion to Can cel the dialogue, in which case the zew 
cal) will faï. 


The promzz atom will be displayed without quotes. 
NOTE 
Tne file selected is not actually create-G by the new primitive; it is simply a user friendly way te 


select a fie name. 
Tnis is the recommended method for allowing the user to specify a file name and volume. 
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12.3 open - open an existing file for read/write access. 
open (file) 
open (file, vol) 
ARGUMENTS 
file : atom. The name of the file to open. 
vol : integer. The identifier of the volume. 
USES 


The named file is opened. If the file has read/write permission associated with it at the operating 
system level, it will be opened for read/write access. If the file is write protected, it will be opened 
for read access only. 


If the file was already open the file pointer is repositioned to the beginning of the file. 


The vol argument will be one that has been returned from a call to oid. 
If the optional vol identifier is not given the default volume is assumed, as recorded by dvol. 


The open primitive is used to open a file that already exists. Information can be read from, or 
written to the file. open is used to signal to the MacPROLOG system that you want to start reading 
or writing to the file. 


Note that open does not allow you to specify that a file be opened for read-only access. A file will 
only be opened for read-only access if it is write protected at the operating system level. 


No backup copy of the open-ed file is made. 


The normal use of open should be in conjunction with old. oid allows the user to select the file 
and volume which are then passed as arguments to open. 


WARNING 

Although you can have many files open simultaneously in MacPROLOG you cannot have two files 
with the same file name (in different volumes) open at the same time. If you try and do this. 
MacPROLOG will just read and write to the most recently opened file. You will not even be able to 
close the previously opened file with the same name. 

This is because once a file has been opened MacPROLOG identifies the opened file for subsequent 
VO operations using just its file name, ignoring the volume. 


ERRORS 


No such volume (-35): 

Disk I/O error (-36): 

File not found (-43): 

File is already open (-47): 
Volume not on line (ejected) (-53): 
No such drive (-56): 

Directory corrupted (-60): 
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12.4 create - create a new version of a file. 


create (file) 
create (file,vol, type) 


ARGUMENTS 
file : atom. The name of the file to create. 
vol : integer. The volume id of where to create the file. 
type : atom, up to four letters. The file s type. 

USES 


A new file of the specified type is created on the volume vol. If the file already exists it is 
sruncated to a zero-length file. Subsequent file output calls will extend the file. 


If the one argument form of create is used the default drive is assumed, as recorded by dvc-. 
and the rype of the file created is 'TEXT'. (See the ols primitive for the allowed fiie types.) 


The normal use of create is in conjunction with new. The preceding call to new 1S used to 
determine the £:le name and vol id to use in the create call. 


ERRORS 


Directory is full (-33): 

Disk is full (-34): 

No such volume (-35): 

Disk Vo error (-36): 

Too many files (-42): 

Fite already open to write to (49): 
Volume not on line (-53): 

File permission error (-54): 

No such drive (-56): 

Directory corrupted (-60): 
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12.5 close - close a file after processing. 
close (file) 


ARGUMENTS 


file : atom. The name of the file to close. 


USE 


The close primitive should be used when you have finished reading and writing to a previously 


open-ed or created file. Itis only when the file is actually closed that you can be sure that the 
disk has been correctly updated with the contents of the file. 


If file is not the name of a currently open file then close does nothing and the call succeeds. 
ERRORS 

Disk is full (-34): 

Disk VO error (-36): 


File not open (-38): 
Disk is write protected (-44): 


12.6 dvol - read / set the default volume 

dvol (vol) 
ARGUMENT 

vol : variable or integer, the volume id. 
DECLARATIVE READING 


vol is the identifier of the current default volume, which can be a disk or a folder. 


USES 


If the vol argument is a variable, dvol will return the integer id of the current default volume. On 
entry to MacPROLOG, the default volume will be the disk or folder on which the LPA 
MacPROLOG™ file resides. 


If the vol argument is an integer, this call will change the current default volume to the specified 
volume. 


Be careful when using this call that you use a valid volume identifier. In general the vol argument 


should only be one that has been returned by a previous call to old or new. If vol is nota 
recognised volume identifier, an error will be generated. 


ERRORS 


No such volume (-35): 
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12.7 seek - report/reposition the file pointer 


seek (file, position) 
seek (file,moda, position) 


ARGUMENTS 
file :atom. Name of a currently open file. 
position : integer or variable. Position of the file pointer. 
mode : integer - value 1, 2 or 3. Reposition mode (see below) 
DECLARATIVE READING 
seek (file, position) : Tne character pointer for file is at position. 
seek (file,1, position) : The pointer for file is position characters 
from the beginning of the file. 
seek (file,2, position) : The pointer for file is position characters 
from the end of the file. 
seek (file,3, position) : Tne pointer for file is position characters 
from the last position of the pointer. 
USES 
l inoz cithe file poaimer. This is the two argument call in which the 





file name is given and positis isa varabie. The primitive returns with the current value of 
the füe pointer for that file. posizicn will be 0 if the pointer is at the start of the file. 





he fis pointer. file gives the name of the file to reposition, and the 
mode indicates in what way the fiie pointer is to be repositioned. The mode indicates whether the 
new position is relative to the star of the file (mode = 1), relative to the end of the file (mode = 2) 
or relative to the current file poinzsr (mode = 3). 
A call 


seek (file, pos) 
where pos is given is equivalent to the call 
seek (file,1, pos}. 


The seek primitive can be used for files that have been opened using open or create. Extreme 
care should be exercised if writing into the middle of a file, as there is no protection against 
overwmiung already existing terms in the file. 


seek can be used to implement a system where one or more programs can be on disk instead of in 
memory. 
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The following is a simple program which allows clauses to be stored in a file; it is the basis of a 
simple relational data base system. 


rpred(F,Oldpos, Goal) :- /* find in the file F a clause that matches 
the goal Goal, starting the search at Oldpos */ 
seek (F,0,Oldpos), /* reposition file pointer to Oldpos */ 
read(F,Cl), /* read in a candidate clause C1 */ 
seek (F,Newpos), /* find new file position Newpos */ 
(Goal=Cl; Goal:-Bdy =Cl, Body; 
rpred(F,Newpos,Goal)). /* either unify candidate clause C1 


with Socal returning Body and 
evaluate 2ody or find another clause 
staring atNewrcrs */ 


You can use this program to keep the clauses for a reisiion -2x¢¢ (say) in the disk file “The lixe: 
file’. To do this replace the clauses for Likes in the program with the single clause: 


likes(%,¥%) :- rpred('The likes fe", r Leees tay.) ) 


The file "The likes file" must also have been ope=.-ed prior to using the program for Likes. Lie 
“The likes file" file should be a 'TEXT' file generatec by a program that uses write to wre cs 
the individual clauses onto the file. 


The Likes clauses in “The likes file" can be quite general, including recursive Clauses, peen 
different invocations of rered can be accessing different segments of the file simultaneously. 7: 
use of seex to record the new position of the file after the next clause has been read means i2- 
each different use of rpred remembers where it is in the file, and then explicitly repositions ‘7.2 


file to that position when it is getting its next clause. 


-3 
- 

=> 

~ 


You can spread the clauses for a relation over several “tes (just use more than one rule of the abc 
form) and you can mix rered definitions of relations with ordinary clauses. So, new informa: >> 
about a data base relation can be recorded by a clause in memory unul the backing store file can 2e 
updated. Programs like rpred can be used to Duild intelligent data base systems wran 
MacPROLOG. 


ERRORS 
File not open (-38): 


Tried to position before start of file (-40): 
Seek error (-32): 
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12.8 delete - delete a file from the disk. 


delete (file, vol) 


ARGUMENTS 

file : atom. The name of the file to delete 

vyol : integer. The volume id where the file resides. 
USES 


This primitive deletes the named file from the identified volume. If the file did not exist then the 
primitive fails. 
Use this call after a call to c `z to establish the file name and volume identifier. 


ERRORS 


No such volvme (-35): 

Disk I/O error (-36): 

Disk is write protected (-4+:: 
File is locked f-45): 

Volume is locked (-46): 


12.9 rename -rename a file. 


rename({old file, vol,new_ file) 


ARGUMENTS 

cad file : atom. Old name of the file. 

new file : atom. New name of the file. 

vol : Integer. Volume where the file resides. 
USE 


The name of old file ischangedto new File. The vol parameter gives the identifier of the 
volume where the file resides. 


Use the ol < and new primitives to establish what file the user wants to rename, and to what new 
name. 


ERRORS 
Renamed file already exists (-48): 
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12.10 ftype -get the type and creator of a file. 


ftype (file, vol, type, creator) 


ARGUMENTS 
file : atom, name of the file. 
vol : integer, volume where the file resides. 
type : variable or atom, the file type. 


creator : variabile or atom, the file's creator. 
USE 


The call may be used to return or check a file’s type and its application. 


The type is an atom of up to four characters (see the description of the old pnmuuve for the f; 


types used by MacPROLOG). 


The creator is an atom of up to four characters and indicates which application created the $: 
Files created by MacPROLOG have 'SIGM' as their creator. 
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13 Execution 


13.1 abort -abort the current process 
abort 
USE 


This call cancels the evaluation currently being executed. 


13.2 halt -exit from \iacPROLOG 
halt 
LSE 
This call will cause an irreversible exit from MacPROLOG. 
WARNING If nalt is called no files will be saved and the '<QUIT>' program will not be 
executed. 
13,3 op - declare an operator 


op(priority,type,op_ name) 


ARGUMENTS 
Prccrity : integer 
tims : atom, operator type 
or name : atom, operator name 
ESE 


This call declares an operator with name cr_ name. 

Tne pricrity argument should be an integer between 1 and 1200, which will determine the 
operator precedence when the operator's arguments are themselves operator expressions. The 
iower the priority number, the more binding the operator (see the Syntax chapter). 


The type argument is one of: 


fx for non-associative prefix operator 
fy for right associative prefix operator 
xf for non-associative postfix operator 
yf for left associative postfix operator 
Xfx for non-associative infix operator 
xfy for right associative infix operator 
yix for left associative infix operator 


When several operators have the same declaration, the op name argument can be a list of 
operator names. 


(See the Appendices for the predeclared operators of MacPROLOG.) 
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13.4 current_op - operator test 


current op(priority, type, op_name) 


ARGUMENTS 
priority : integer or variable 
type : atom or variable, operator type 
op name : atom or variable, operator name 
USE 


If sp name is an atom, the call can be used to find the priority and type of a given operator. 
(See the op primitive for a list of operator types.) 


= 


op_name isa variable then the call c2zzenz_cz may be used to backtrack ihrough operators. 
and in this case if either tyge or pricrity is an atom then only operators of that p'e anc cr 
riority will be retneved. 


fo 


t4 


13.5 spy - set spypoints 

spy (pred) 
ARGUMENT 

pred ; atom or list of atoms 
LSE 


Tre pred argument may be either a single relation name or a list of relation names. The call seis 
savpoints on the specified relations. 


This is equivalent to the Spypoints menu commana of the programming environment. 


13.6 nospy - clear spypoints 

nospy (pred) 
ARGUMENT 

pred ‘ atom or list of atoms 
USE 


The pred argument may be either a single relation name ora list of relation names. The call clears 
spypoints from the specified relations. 
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13.7 nospyall - clear all spypoints 


nospyall 


USE 


This call clears all spypoints currently set. 


13.8 trace - set tracing on 
trace 
CSE 


Tracing of interpreted relations is switched on. (See the Environment Guide for a description of 
acing of programs.) 


oP, notrace - switch tracing off 
notrace 
LSE 


This call switches tracing off. 
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13.10 unknown - set action on undefined relations 


unknown (old _ action,new_ action) 


ARGUMENTS 
old action : variable, previous action 
new action : atom, new action 

USE 


When an undefined predicate is encountered during an evaluation there are different ways of 
dealing with it (provided it is not dynamic - see the dynamic primitive below). 


The new action argument specifies what action should be taken when an unknown relation 
name is encountered, and should be one of 


rh 


A fe 


t4 ty A 
D D t 
M 


c+ ct 


— 


The fail option will cause the unknown call to fail. 


The trace option will cause the error handler to be cuiied {see the chapter on Implementing an 
Application). 
The true option will make the unknown call succeec. 


The old action argument returns the currently desinec action procedure. 
The call 


unxnown (Action, Action) 


will simply return the current action without changing :t. 


13.11 dynamic - declare dynamic relations 
dynamic (pred) 
ARGUMENTS 
pred : atom or list of atoms 
ESE 


This call is used to over-ride the unknown action for the relation or relations specified by Le 
sred argument. If an undefined dynamic relation is encountered i: will automatically fail. 
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13 : Execution 


13.12 ticks - return the system elapsed time, or wait for a time 

ticks (time) 
ARGUMENT 

time : variable, or non-negative integer 
USE 
If time is a variable it will be bound to an integer which is the number of 60ths of a second that 
have elapsed since the system was booted up. It may be used to time the amount of processor time 
taken by certain calls. 


If time is an integer, then program execution is suspended for t ime 60ths of a second. 


(This timing mechanism is not totally reliable since heavy use is made of interrupts within the 
Macintosh, and time taken for processing interrupts is not removed from the system clock.) 
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14 Serial I/O 


The following primitives give access to the printer and modem serial ports. Once a channel has been 
opened and configured, data may be read from and written to the ports using the general I/O 
primitives read, write etc. specifying the channe! to be either printer or modem. 
WARNING: There are some known problems associated with use of the printer port; for example 


there may be interference with Appletalk, or the printer port may not work at all, depending on your 
version of the operating system. 


14.1 seropen - open a Serial channel 


seropen (channel) 
ARGUMENTS 

channel : atom 
USE 


This primitive opens the specified serial channel. 
The channel argument should be either printer or =ccem. 


14 : Serial VO 


14.2 serconfig - configure a serial channel 


serconfig (channel, port, baudrate, databits, parity, stopbits) 
ARGUMENTS 


channel : atom 
port : atom 
baudrate : integer 
databits : integer 
parity > atom 
stopbits : number 


SE 
Tnis call configures the specified serial channel. 
Tne channel argument should be either printer or modem. 
Tne port argument must be one of the atoms: 
a out DOTE 
ċepending on whether the channel is to be used for input, output or both input and output. 
The baudrate argument is the baud rate setting for the channel. 
i: must have one of the following integer values: 


250 60C 1290 18C% 2400 3600 4800 7200 $600 19200 57600 


NOTE: The maximum baud rate for the printer port is 300 for input, and 9600 for output. 


Tne databits argument is the number of data bits per character, which should have the value =, 
E, 7 OF &. 
t 


The parity must be one of the atoms: 
ocd even none 


The stopbits argument is the number of stop bits. It should have the value 1, 1.5 or 2. 
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14.3 serstatus - get the status of a serial channel buffer 


serstatus (channel, port, count) 


ARGUMENTS 

channel : atom 

port : atom 

count : variable or integer 
USE 


If count is a variable, this call is used to find the number of characters remaining in the serial 
buffer. 


If count is an integer, the call will succeed if there are sc unt characters remaining in the senal 
buffer. 


The channs1 argument must be either orinter or=caen. 
The port argument must be either in or cut. 


14.4 serxonxoféf - enable Xon/Xoff flow control 
serxonoff (channel) 

ARGUMENT 
CAS es : atom 

LSL 


This call enables Xon/Xoff data flow control (the Xon anc Xoff characters are Contrei-Q and 
Control-S resoecuvely). 


14.5 sercts - enable CTS hardware handshake 
sercts (channel) 
ARGUMENT 
mannel : atom 
USE 
This call enables CTS hardware handshake. 


=- 


The channel argument should be either crinter or modem. 
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15 Menu Handling 


MacPROLOG has several primitives that enable you to create, manipulate and delete the pull-down 
menus of the menu bar at the top of the Mac display. 


If you add a new pull-down menu with name Name, Name must also be defined as a unary 


relation. When the user uses the mouse to select an item Item from this menu, this is equivalen: 
to calling the relation Name with argument Iten, Le. it is equivalent to the call 


'Name' ('Item') 


If Name is not defined there will be an error message to the effect that the menu is not defined. The 
invoked Name program can be interpreted or compiled. It can display dialogues, create windows. 
or even change the menu bar. It can ultimately succeed or fail. At the end of the evaluation the use: 
can again select a command from the menu bar. 


Al! the menus of the programming environments, except the File and É menus, are implemente 
a: MiacPROLOG programs. 


- A 
am 24 


y. 


taąali_menu - create a new pull down menu 


install menyu (name, iter list 
APU NLON ES 
zme aer mame cf menu 
Sten List list of atoms, menu items 


any exising pull-down menu calied name is deleted and a new pull-down menu is added to tne 
ment bar to the right of the current nghtmost menu.The item list contains tne items to appez: 
wn the menu. 


The item list can either contain a single quoted atom with the menu items separated by 
semi-colons, or it can contain the items as individual atoms (see the example below). 


The menu item names can contain extra control information as prefix or postfix character 
sequences. 


A quoted atom name ending with / followed by a capital letter associates a control key with that 
enu item. (The Macintosh ‘control’ key is the one marked 3% on the keyboard.) For example, 


‘Item/G' 


will associate with the menu item name Item the control key % G. Typing 9% G will then be 
equivalent to selecting that menu item. You should make sure that the control characters associated 


with different menu items are distinct. (But if you assigned $$ G toasecond menu item the /G 
would be ignored for that second item.) 


15 : Menu Handling 


If a quoted atom name is prefixed by around bracket ( then the item will initially be disabled, i.e. 
it will appear in grey and cannot be selected by the user. (See also the primitives enable_item 
and disable item.) 

To insert a horizontal separating bar between two items in the menu, separate the item names in 
item_list with the atom '(-'. 


EXAMPLE 


The following call will create a four item Fruit menu with pears initially disabled, and a 
horizontal separating bar between kiwi fruit and Grapes. Pressing 3% G will be equivalent to 
selecting Grapes from the menu. 


install menu('Fruit', 
lapples,'(pears’,'kiwi fruit','(-', 'Srapes/G';) 


apples 
pears 
h 


kiwi fruit 


Grapes #6 7 





This is also equivalent to the call 
install menu('Fruit', [’apples; (pears; “iwi fruit; (-;Grares;s3')) 
Remember that there must be a program of the following form defining ‘Fruit’: 


Fruit Gapples).= 
/* clause for apples option */ 


‘Fruit! (kiwi. fruit’) >- 
/* clause for kiwi fruit option */ 


and similarly for pears and Grapes, otherwise an error will be generated when one of the menu 
items is selected: 


Sorry, ‘Fruit’ is not 
( implemented 
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15 : Menu Handling 


15.2 kill_menu - delete a menu from the menu bar 
kill menu (name) 


ARGUMENT 


name : atom, name of a menu 


SIDE-EFFECT 


Tne menu name is deleted from the top menu bar. The associated program which defines nam 
is not deleted. 


PRAGMATICS 


You can use this primitive to delete the menus of the programming environments as well as your 
own menus. However, do not delete the @ menu or the File menu. 


> =á 
ma 


.3 clear menu - remove all items from a menu 
clear menu (name) 
ARGUMENT 
name : atom, name of a menu 
SIDE-EFFECT 


This will erase all the entries in the menv. but leave the menu name on the menu bar. It may be 
used before inserting a new set of entries for a menu. 
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15 : Menu Handling 


15.4 disable menu - disable a menu 


disable menu (menu) 


ARGUMENTS 


menu : atom, name of a menu 


USE 


The whole menu menu is disabled. The menu name appears ‘greyed our in the menu bar, and all 
its items also appear in grey if the user pulls down the menu. Indiviczal items in a disabled menu 
may still be disabled or enabled with disable itemorenat_¢_ item, but enabled items 
cannot be selected by the user until the menu itself is enabled. 


EXAMPLE 


The Fruit menu descntec 2: the peginn.ng of the choner may becir 26 by theca. 


= 


aoe : 
_ - t 
G me cae he e tae 








apples 
pears 
knre: fyi 





PTT TTI TET TLL LCi re 


Nojtem frosts menu may BOW’ De Sesecsec. 


ARGUMENTS 
mers - atom, name of a menu 
USES 


The whole menu menu is enabled. Its name appears i~ Diack on the menu Car. and iii tems (exces 
those individually disabled by disacls_ item j can row be seleci2c. 
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15 : Menu Handling 


15.6 extend menu - extend a current list of menu items 


extend menu (menu, items) 


ARGUMENTS 

menu : atom, name of a menu 

items : list of atoms, new menu items 
USE 


The list of items of menu is extended below by the extra items. The menu item names have the 
same form as for install_menu. 


12.7 Cisable item - disable a menu item 


wei 
wae eek LIT 


Ro a TE 
a Sk ae Se 


panes females. eais Oe a sempil 
T E E ClO ME na on aalsa Daaerel 


sS 
JQ 
bets | 
M 
- 
¥ 

Y 


Tne 2 ces o ment is dises.ec. itcannc: now ve selected. The d:saoled nen epeears 
Ou: in the menu and is nci highlighted when te user moves the mouse over the item. 


I3 enable_item - enable a previously disabled item 


enable item(menu, iter) 


ARGUMENTS 
menu : atom., name of 2 menu 
icem : atom, name cf menu item 
USES 


The item of menu is enabled. It can now be selected by the user, and will appear in black on the 
menu display. 
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15 : Menu Handling 


15.9 mark item - mark a menu item 


mark item(menu, item) 
mark item(menu, item, code) 


ARGUMENTS 

menu : atom, name of a menu 

item : atom, name of menu item 

code : integer, ASCII code of mark character 
USE 


1. Two argument call The item of menu is marked with a tick. Such a marking can be used :: 
indicate the setting of some global flag. Whether or not an item is marked can be tesied with i7: 
marked item primitive. 


2. Three argument call If an integer is given as a third argument. the integer 1s interpreted us -7 
ASCII code and that character is used instead of a tick to mark the menu Item. 
Some codes you might like to use are: 


17 - #& 
19 - + 
20- é 
For example. the items apples and kiwi fruit may be marked using the two calis: 


and márk- item tuit 7 Kowa Irure 








éapples 
pears 
“kiwi fruit 


Grapes 36 


15.10 unmark_item - unmark a marked menu item 


unmark item(menu, item) 


ARGUMENTS 
menu: : atom, name of a menu 
item : atom, name of menu item 
USE 


pe 
ifi 


The previously marked item of menu is unmarked - the tick (or other mark character: 
removed. 
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15 : Menu Handling 


15.11 marked item - test if a menu item is marked 


marked item (menu, item) 


ARGUMENTS 
menu : atom, name of a menu 
item : atom, name of menu item 
USE 


It is used to test if the item of menu is currently marked. If it is the call succeeds, otherwise the 
call fails. 


15.12 rename _item - rename a menu item 


rename item(menu,itez,new_ item) 


ARGUMENTS 
menu : atom, name of 2 menu 
iten : atom. name of menu item 
new item : atom, new name for menu ite 
USE 


The iter of menu is renamed new iten. 
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15 : Menu Handling 


15.13 style item - change the style of a menu item 


style item(menu, item, style) 


ARGUMENTS 
menu - atom, name of a menu 
item : atom, name of menu item 
style : atom, name of an item style 
USE 


The item of menu will be displayed in the designated style. The allowed values for the style 
argument are the atoms: 


normal 
boid 
italic 
unceriine 
shadow 
condense 
extend 


For example, the following program would change the Eval menu as shown below. 
change eval:- 


style item('’Eval', ‘Clear all s24 soints o condense) ; 
styie item('Eval', 'Tracing',ex tend). 


Query... 
Check program 


Set spy points... 
Clear all spy points 
Tracing 

Trace model... 





PRAGMATICS 


Styles can be used to give status indication to the usec. 
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16 Predefined Dialogues 


Dialogue windows may be used to give information or to accept input from users during the 
running of a program. You can build your own dialogue windows, or use some of the predefined 
dialogues of MacPROLOG. This chapter describes the predefined dialogues available; see the 
chapters on Dialogue Building and Advanced Dialogues if you wish to build your own. 


There are two types of dialogues: Modal and Modeless. 


A modal dialogue must be answered before anything else is done. You cannot select another 
window or pull down a menu whilst a modal dialogue is displayed. You must respond to the 
dialogue. 


A modeless dialogue does not need to be immediately answered. You can select some other 
window, scroll it, edit it, and paste text into the modeless dialogue edit fields. You can also 
execute any command of the puli down menus before responding to the dialogue. This means that 
you can even Start a second MacPROLOG process. The process that created the modeless dialogue 


will be suspended until you seiect the dialogue and click its OK or Cancel button. At that poin: 
the suspended process is resumed. Modeless dialogue windows may also be moved around the 
screen. 


Keyboard input during an evaluation can be achieved using primitives that display dialogues 
containing a prompt message and an edit field into which the users may type. On hitting Return or 
clicking the Ok button of the dialogue, the typed input is bound to the variable of the invoking call. 
Clicking the Cancel button of the dialogue causes the call to fail. 


The primitives prompt_read and prompt_gread read arbitrary terms. These two display 
modeless dialogues. 


The primitive ask invokes 2 modeless dialogue which accepts arbitrary user input without 
performing any syntax checks. 


The primitives yesno and myesno invoke dialogues which display a message that requires only a 


yes/no answer via dialogue buttons. yesno creates a modeless dialogue, myesno a modal 
dialogue. | 


There is also the primitive scroll_menu which displays a scrolling menu of a supplied list of 
atoms from which one or more items may be selected with the mouse. This is a modal dialogue. 


There are three special purpose dialogue primitives for giving warnings and messages - message, 
warning, and errormessage. 


Another primitive, banner, provides a non-interactive dialogue for the display of information to 
the user, which will terminate on the completion of a specified goal. This can be used to give 
information to the user during time-consuming processes such as loading large files. 


An online help facility may be implemented using the help primitive. This reads text from a help 
file and displays it on the screen in a dialogue. 


16 : Predefined Dialogues 


16.1 prompt read - prompted read of hollow term 


prompt _read(prompt_ list,term) 


ARGUMENTS 

prompt list : a list of terms 

term : a variable, will be the term read in 
USES 


A modeless dialogue is displayed with an edit field into which the term must be entered. The 
prompt message comprises the sequence of terms in srompt_ lisz separated by spaces. Ir. 
other words, prompt list will be displayed without the outer list brackets and without the 
separating commas between the terms on the list. Also atoms will not be quoted. 

The characters entered into the edit field of the dialogue will be read in as aterm. A terminating fz: 
stop 1s not needed but can be entered. 


Variable names in the entered term are converted into vanables. The entered term becomes the 
binding of the term argument when the Return xey is hit or the OK button of the dialogue :s 
selected. Selecting the Cancel button causes the cz to fail. 


The call 


DEOmpe. read{ "Give a SOLluUCl os POr = ty 
Gives (spicer,X, Y}),&2,2,iist!,2 


will generate the dialogue: 







Give a solution for - gives(spider, _1121, 1122) as 
a list 






(the variable names will be different). If :he user types 
(fright; Miss Marre] *: 


into the edit field of the dialogue then the varizdòle 2 of the cali will be beung to the is 
“2rivgGnt; ‘Moss Murtet” }. 

Note that if the user simply presses Rerurn or clicks on the OK bution without typing anything. 
then the variable Z will be bound to the atom end_cz_ file. 


If there is a syntax error in the edit field, an error dialogue will be displayed - see 
prompt gread. 
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16 : Predefined Dialogues 


16.2 prompt _ gread - prompted read of ground term 


prompt _gread(prompt_ list, term) 
prompt gread(prompt_list,term, varnames) 


ARGUMENTS 

prompt list : a list of terms 

term : variable, will be read-in term 

varnames : variable, will be variable names of the read-in term 
USE 


The two argument form has exactly the same use as prompt_ reac except that variable names in 
the read-in term are left as atoms. They are not converted into variables. (They will be displayed 
as quoted atoms if you writes the term.) 


The three argument form aliso displays the same dialogue and reads in ground terms. The 
difference is that the third argument will be bound to the list of variable names of the read-in term. 


The call 






enter a condition to be solved 





If the response is to enter 
likes (keitr:, People) 


into the edit field, then Gterm will be bound to likes (keith, 'People') and Varnames 
will be bound to ['Peopie']. 
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16 : Predefined Dialogues 


PRAGMATICS 


Use the two argument form of this primitive instead of prompt_rsad when you know that the 
input sequence of terms will not need to contain variables and you do not want the user to have to 
remember to quote upper case names. 


Use the three argument form when you want to remember the variable names of the read-in terms. 
You can always convert the read-in term into a hollow term using the zchollow primitive. 
For example, after the above prompt_gread call, the call 


tohollow(Gterm, Hterm, Varnames) 


will result in Hterm becoming likes (keith, 122) in which 722 is a real variable which 
can be bound by a unification. 


By using prompt gread and then tohncllow rather than promr~_ ead you have retained the 
variable name used in the call which can be used when the solution is cisplayed. 


ERRORS 


If the user clicks on the Ok button and there is a syntax error in the ec:: field, a modal dialogue wii 
be displayed at the bottom of the screen: 


8 Syntax error in an edit field of the 
dialogue 





The user must then click the OK button on this dialogue and retum io the premret_areacier 
crompt_read) dialogue to either correct the error or cancel the C:2.¢gue. 
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16 : Predefined Dialogues 


16.3 ask - prompted read of arbitrary input 


ask(prompt_list,input) 


ARGUMENTS 

prompt list : a list of terms 

input : variable, will become a list of tokens 
LSE 


To accept input from the keyboard as a sequence of atomic terms. No syntax checks are made on 
the input. 


A modeless dialogue is displayed with an edit field, Ok and Cancel buttons, and a message 
formed from the prompt list argument. The terms of prompt_list are displayed as a 
seauence of terms separated by spaces, as with prompt_ read. 


Tne input argument will be bound to a list of the ‘tokens’ entered in the edit field of the dialogue. 


A token is any symbol, word, separator, etc. (for more information about tokens see the edintcx 
CTLMutive). 


ask ([{'Enter',a,sentence,to, parse}, List) 
p 


vili display a dialogue with an empty edit field into which the user types text. 













wot ETI oe ee Pega S58 th ar AE a i A EER E a e T eb aga 
EES See er E Ea E A Ses ORLA RE. 


` 
” 


The boy kissed the girl, in a wheelbarrow 














If the user enters the above text, then List will be bound to the list of tokens 
['The',boy,kissed,the,girl,',',in,a, wheelbarrow] 


Tne calling PROLOG program may then process this text in an appropriate way (for example al] 
punctuation may be ignored). 


The ask primitive is useful when you are not necessarily expecting valid Edinburgh syntax terms. 
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16 : Predefined Dialogues 


16.4 yesno - display a prompt that requires a yes/no answer 
yesno(prompt_ list) 


ARGUMENTS 


prompt list : a list of terms 
USE 


To get a yes or no answer to a question. yesno displays a modeless dialogue with Yes andNo 
answer buttons and a message formed from the premst_list argument. 


The sequence of terms of the prompt_list argument is disp.ayed as a sequence of terms 
separated by spaces, as with prompt_ read. 


The only allowed response is selecting the Yes or the NO button cn the dialogue or hitting the 
Return key. 


If the Yes button is selected or Return is hit the call succeeds. 


If the NO button is selected the call fails. 
EXAMPLE 
The call 
yesno(({'Is "wheelbarrow" a oe A 


displays the dialogue 
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16 : Predefined Dialogues 


16.5 myesno - display a prompt that requires an immediate yes/no answer 
myesno(prompt list) 

ARGUMENTS 
prompt list : a list of terms 


USE 


Exactly the same as yesno, except that the dialogue is modal and so the user must respond by 


clicking on either the Yes or NO answer button on the dialogue before doing anything else. Any 
attempt to select another window or pull down a menu before responding to the dialogue will cause 
the bell to sound. 


EXAMPLE 
The call 
myvesno(['Does the bicycle have a flat tyre?'])) 


will display the following dialogue. 


N Does the bicycle have a flat tyre? 
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16 : Predefined Dialogues 


16.6 scroll menu - display a scrolling menu for item selection 


scroll menu (prompt_list,menu_ list, 
preselected, selected) 


ARGUMENTS 
prompt _ list : a list of terms 
menu list _ ta list of atoms 
preselected : alist of atoms 
selected : a variable 
USE 


To allow selection of one or more items from a given list. A modal dialogue containing a scolling 
menu is displayed. It must be responded to before anything else 1s cone. 


The scrolling menu dialogue is displayed with the senu_list atoms as the menu items and with 
the sublist of the preselected atoms already selected (i.e. in reverse video). Using the mouse 
click and shift-click, the list of selected menu items cen de changed. No item need be selected. 


On hitting the Return key or upon selecting the OK button of the dialogue the call succeeds with 
the selected variable bound to the list of selected items in the menu. On selecting the Cancel! 


ao T unk 


button the call fails. 


As with the other dialogues, the prompt_lis: wiil be displayed as a sequence of terms 
separated by spaces, and atoms will not be sie 


The call 
SLL _menu({'What do you @r.7 Ss Eoine.* y 
(singing, “lion ca Lo eee Se ec wey 
twind Surfing’, usi a ZrO T} 


a2 On anoh =) 


will result in this scrolling menu being displayed: 


What do you enjoy = jsinaing 
doing? A 





if the selection is extended by shift-clicking on usinz PROLCS before the Ok button is selected 
then S will be bound to the list ['lion taming', 'using PROLOG']. 
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16 : Predefined Dialogues 


16.7 message - display a modal dialogue with a message 
message ( term list ) 
ARGUMENTS 
term list : list of terms to be displayed 
USE 


A modal dialogue is displayed on the screen. The terms in the term_list will be displayed 
inside the dialogue as a sequence of terms separated by spaces, and with no outer list brackets. 


The dialogue also contains an 0k button which the user must click on before continuing. 


Notice that message is purely for the display of information, since the user is not given any 
options. Tne only course of action availabie is to click the OK button. 


EXAMPLE 
Tne call 


ressage(['You have mace á mistaxe. ~MPlease correct it.']) 


cisplays the modal dialogue 








You have made a mistake. 
Please correct it. 


Note the use of the ~M in the prompt_ 2 sz argument to denote a carnage return. 
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16 : Predefined Dialogues 


16.8 warning - display a modal warning dialogue with a message 


warning(term list) 


ARGUMENTS 


term list : list of terms to be displayed 


USE 


A modal dialogue is displayed on the screen. The terms in the term_list will be displayed insice 
the dialogue as a sequence of terms separated by spaces, and with no outer list brackets. 


The dialogue also contains a Continue button and a Stop button. If the user clicks on the $top 


button the current process terminates; if the user clicks the Continue button the process 
continues. 


EXAMPLE 
The call 


warning (['WARNING:', 'The er 


i 
(} 
th 
qt 
7 
M 
= 
0 
{ 
? 
ñ 
3 
? 
J 


w — A ma tt kb am ana 


will display the modal dialogue 





i WARNING: The end of the world is nigh | Continue | | 
| Stop | ) 
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16 : Predefined Dialogues 


16.9 errormessage - display a modal error dialogue with a message 
errormessage (term list) 

ARGUMENTS 
term list : list of terms to be displayed 

USE 


A modal dialogue is displayed on the screen. The terms in the term list will be displayed 
inside the dialogue as a sequence of terms separated by spaces, and with no outer list brackets. 


The dialogue also contains a Stop button which the user must click on. This terminates the current 
process. 


EXAMPLE 
The call 
errormessage(['The ens ct the world has come']) 


will display the following cialogue. 


W The end of the world has come 





ee 


16.10 banner -display information during a process 


banner (call, message) 


ARGUMENTS 
call : term representing the goal to be executed 
message : term Lis: the message to be displayed 
USE 


This primitive displays a non-interactive dialogue box on the screen (it has no buttons). Tne 
message list will be displayed in the usuz: way (i.e. as terms separated by spaces with no outer 
list brackets). The call is then executec. and when the evaluation is completed the dialogue 
terminates. A call to banner always succeeds, regardless of whether or not cail succeeds or 
fails. 


For example, the following call will give an information banner whilst loading a file. 


banner (consult ('Large File'), 
['Please wait - loading','Large File'}) 
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16 : Predefined Dialogues 


16.11 beep - sound the bel! 
beep (time) 
ARGUMENT 
time : integer 
USE 
This primitive will cause the system to beep for the specified time (in 60ths of a second). The 


volume of the beep depends on the current speaker volume setting, which the user can set from the 


Control Panel desk accessory. If the speaker volume has been set to 0, beer will cause the Menu 
Bar to blink once. 


16.12 help - online help facility 


help(file, subject,title, text) 
help(file, subject, title) 


ARGUMENTS 

file - atom, the name of an ASCII text file 

subject atom, a main entry in the help file 

ticle - atom or variable. A sub-entry in the sut ject 

text - variable. Becomes the help associated with svbjesr anrd titis 
LSE 


This call is used to provide an online he!p facility. The information to be displayed is stored in ine 
ASCII text file £i le, which must be in the current cefault volume when cele is firsi called. 


` Four argument use 
-axt will] be bound to the atom (up to 255 characters: corresponding to the entry tor sus 27 
and title inthe help file named by fiis. 





if -itle is not given and there are multiple entries for subjes then there will ce mulung 
solutions to the call. 


> _ Three argument use 
Similar to the four argument call, but instead of returning the help constant as the value of zn 


argument, the subject, title and help text are displayed in a modal dialogue with a single OK 
button. 
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16 : Predefined Dialogues 


For example, in the MacPROLOG programming environment the call 
help('Menu Eeip', 'Windows', 'Alphabetical') 


will display the following dialogue 


Windows 


Alphabetical 


MARKED: Display windows in alphabetical order when 
cleaning up, etc.. 


UNMARKED: Display windows according to their creation 
date. 





The on-line help for puli-cown menus in the MacPROLOG programming environment is 
implemented by programs such as 


‘Seelen tos 2ecall(s82p¢0n) + | 
SPeilp« Menu Help’, Search’; C):. 


"Search ( Vne= TO fang ses his 
'* program for this menuitem */ 


and so on, 

The first clause above tests to see if help mode is on. You can define your own menu programs in 
the same way, accessing your own help file. 

SIDE EFFECTS 

The initial call to help for some file will cause the complete contents of the file file to be 


loaded into an invisible dispiay window with the same name. It is actually this display window 
which is used as the source of the help information. 
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For users who wish to make use of this facility in their own applications, there is a simple structure 
for the help file. Each entry in the file specifies the subject and title of the help item, followed by the 
text for this item enclosed in comment brackets /* and */, i.e. an entry is of the form 

subject title /* ... text for this item ...%*/ 
The title may be omitted: 

subject /* ... text for this item ... + 


which is equivalent to 


subject '' /* ... text for this item ... =y 


NOTE: 


a) It is important that there are spaces on either side of the “* and * ’ in the help file. If there are no 
surrounding spaces, /* or */ will be not be correctly recognised as Gelimiters of the text. 


b) Different entries for the same subject do not have to be contiguous in the help file. Tre 
display window is simply searched for matching text, 11 is not compiled. 
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17 Dialogue Building 


There are two powerful primitives that enable you to define, display and extract information from 
dialogues. dialog is for labelled modeless dialogues and mdialog is for unlabelled modal 
dialogues. See the chapter on Predefined Dialogues for a description of the differences between the 
two types of dialogues. 


Both primitives allow you to define and use dialogues with icons, text fields, edit fields, check 
boxes, radio buttons and ordinary buttons. In addition, one scrolling menu is allowed in a modal 
dialogue. | 
MacPROLOG also allows picture items in dialogues. For a description of these, and of other 
special dialogue handling features, see the chapter on Advanced Dialogues. 


17.1 dialog - display and read from a labelled modeless dialogue 


dialog (title,down_pos,in_ pos, depth, width, 
format list, button) 


ARGUMENTS 
title : atom. label displayed at top of dialogue 
down pos : integer, position of top of dialogue as a number of pixels 


cown from the top of the Mac display. 

Tris should be at least 40 to avoid the menu bar. 

The overall depth of the Mac Plus display is 342 pixels. 
in pos ‘integer, position of left of dialogue as a number of pixels 

in from the left of the Mac display. 

Tne overall width of the Mac Plus display is 512 pixels. 


depth : integer, depth of the dialogue in pixels 

piaski : integer, width of the dialogue in pixels 

format list :Estof dialogue field format descriptors - see below 
burton : Variable, will become an integer indicating 


which button was selected 
USE 


A call to this primitive displays a dialogue of the size and position specified with edit, button anc 
other fields as specified by the format _*ist. The dialogue has rounded comers and the tte 
is displayed in a title bar across the top of the dialogue. 


When the user selects one of the buttons on the dialogue - displayed as oval fields - the number of 
the button selected will be returned as the value of the variable button. This number is the 
position of the format descriptor of the selected button within the format_list. 


17 : Dialogue Building 


As a general rule, the first two items in the format list should be button descriptors. The first item 
should be an OK button, corresponding to the normal response to the dialogue. The second item 
should be a Cancel! button, corresponding to the user's wish not to respond to the dialogue. If 


the Cancel button is selected, that is if the value that would be returned for button 1s 2, then 
the call to dialog fails, and none of the other dialogue fields are read. 


If the user hits 38. (the 36 key with the full stop key) this is also a cancel action and it also causes a 
failure of the call. If the second format item is not a button this is the only way to cancel the 
‘dialogue and fail the call. 


If any button other than the Cancel! button is selected, that is any button with a format descriptor 
which is nor the second descriptor on the format list, and there are no syntax errors in the eci: 
fields of the dialogue, the call succeeds. The value of button tells you the button that has beer 
selected. All the other fields in which the user might have entered information, such as chec: 
buttons, radio buttons and edit fields, have their values read in to variables supplied as part of trex 
format description in the format list. 


If the user hits Return, this is also interpreted as a normal response to the dialogue and the value of 
button will be 1. Again, the other field values will be read in to the variables of the format 
descriptors, providing there are no syntax errors in the edit fields, 


If there are syntax errors in an edit field of a dialogue, a modal error dialogue will be displavec. 
The syntax errors must then be corrected (or the dialogue cancelled). 


THE FORMAT DESCRIPTORS 


The field format descriptors are all terms of the form 


where 
field type isan atom giving the type of the field 
dora “pos is an integer giving the relative position of the top Of the eld os. 
number of pixels down from the top of the dialogue. 


This should be at least 40 to avoid the tue Dar. 


2e DOS is an integer giving the relative position of the left of the field z5 2 
number of pixels in from the left of the dialogue 


Gerth is an integer giving the certh of the field in pixels. This shouic 22 
at least 20 for fields that will hold text. 
A line of text is 16 pixels high. 


width is an integer giving the width of the field in pixels. 
For fields that will hold text allow 10 pixe!s for each character. 


and the ... extra parameters depend on the type of the field. 


Where the type is a field from which values will be read the last parameter is always a variable cr 2 
term containing variables into which the field values will be read. 
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The allowed field descriptors for a modeless dialogue are as follows. 


l. edit (down_pos,in_pos,depth,width, 
initial value, final value) 


This creates an edit field within the dialogue of the size and position specified. The edit field 1s 
displayed as a rectangular box. The initial value parameter is a term giving the display 
format and value of the initial contents of the edit field: the contents that the user will be able to edit 
The final value isa term indicating the read back format of the final contents of the edit field. 
The final value format term must contain one or more variables to hold the read-in values. 


The ability to prefill an edit field is extremely useful. It enables you to build an application in which 
the user's entered values are anticipated with default values. You can use the interpreted data base 
or the property management primitives to remember a default value, which might be the value 
entered into the edit field when the dialogue was last displayed. The read back format does not 
need to be the same as the prefill format. 


The allowed prefill formats for the initia-_value term are: 


¿atom i azom is an atom. The atom will be displayed in the edit field 
unquoted. This enadles you to preload an edit field with a sequence ot 
characters and spaces given as a quoted atom. To leave the edit field empty. 
use the empty quoted atom ''. 


“riteq(iterm) iterm is any term. The term will be displayed in the edit field as though 
it were written with «rite. 


ti 
p>? 
ct 
d» 
Q 
t- 
rt 
{b 


rm, vns) itezrmis any ground term, vns is a list of quoted atoms that are 
usually variable names in iterm. The term will be displayed in the ea:: 
field as though it were written with writeg except that atoms in vns wil 
not be quoted. This is the format you should use to display user inputs thet 
have previously been read in from the edit field using the gread format. 


zyres (bytes) bytes is a list of byte codes. The list of bytes will be displayed 
concatenated as a sequence of characters. For example, oytes([€-2 
66,67]) will be displayed as the text ABC. 


t 


zokens (toks) toks isa list of toxen terms (see the description of the use of tokens 
as a read back format). The main use of this prefill format is to redisplay in 
an edit field a sequence of tokens read in from a previous use of the 
dialogue. 


words (wds) was isa list of atomic terms The list will be displayed in the edit field as a 
sequence without the surrounding list brackets and without the separating 
commas. The items on the list will be separated by spaces. 
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The allowed read back formats for the final_value term are: 


f atom 


read(fterm) 


gread(fterm, vns) 


bytes (bytes) 


~okens (t218) 


f atom isa variable. The final character sequence contents of the edit 
field will be read back in as a single atom which will become the value of 
the variable £ atom. If need be, you can then parse this by using name to 


' map the atom into a list of bytes. 


fterm isavariable. The final character sequence contents of the edit field 
will be read back in as aterm. Variable names in the term are replaced by 
variables. 


fterm andyns are variables. This is exactly the same as 
read(fterm) except that variable names in the read-in term are left as 
atoms and the list of all the variable names in the read-in term are returned as 
the binding for vns. The read-in term can be subsequently converted to 4 
hollow term using zohollc«. See the description of pro=s2_gres- 
for an example of the possible use of this format descriptor. 


bytes is a variable. It will be bound to a list of the ASCII codes of the 
sequence of characters entered in the edit field. For example. if ine enterec 
text is ABC bytes will be bound to the list (£5, 66, 67}. 


' toks is a variable. This wiil be bound to a list of terms of the form 


token (token, -ype) where zoken is an Edinburgh syntax token anc 
type is the integer identifier of the token type. The possible coxen types 
are: 


QO Separator (‘'or'. ' space or dot space) 

1 Punctuation (either ' (' -t tert eje tet tet tat ert, |) 
2 Single character symbol (*:' '/') 

3 Symbolic name (sequence of graphic characters e.g. ££ 

4 Uppercase name (alphanumenc starting with uppercase lerer or '_') 
5 Lowercase name 

6 Number (only positive numbers) 

7 String 

8 Quoted atom 


In effect, this format descriptor causes the entered text to be tcxenised anc 
returned as a list of the enterec sequence of tokens. 
For example, if the entered text is 


(mary, 4, !] 


. toks will be bound to the list of terms 


[(token('[{',1), token(mary,5), token(',',+), 
token(4,6), token(',',2), token(!,2), 
tokeni I yA] 
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words (wds) wds is a variable. This will be bound to a list of the tokens of the edit field. 
This is the same list of tokens as returned by tokens except that the token 
type is not given. 
For example, if the entered text is 


Clare, dave and brian like cats 
was will be bound to the list of tokens 
{clare,',',dave,and, brian, like,cats] 


Use words if you want to access the entered text as a list of atoms. No 
syntax checks will be made on this input. 


2. text (down_pos,in_ pos,depth,width,text_value) 


This creates a text field within the dialogue box at the position specified. The zext_valus 
gives the display format and value for the text to be displayed. It will appear without a surrounding 
rectangle. 


The allowed formats for texż_value are the same as the prefill formats for an edit field with the | 
addition of: 


wseq(iterm list) iterm_list isa list of terms. The terms in the list will be displayed 
in the text field as a sequence of terms separated by spaces (not commas) 
and with no outer list brackets. Each term is displayed as though it were 
written with write. For example, if the text format is 


wsed ( 
(ls: the: olLlowing condition trues"; 
likes (xeith,mary),?)) 


then the contents of the text field will be 


Is the following condition true: likes (keith, mary)? 


3. button (down_pos,in pos, depth, width, label) 


This creates a button field within the dialogue of the size and position specified. The button field is 
displayed as a rectangular box with rounded corners. The label must be an atom, which is 
displayed in the button field. A button is selected using the mouse. 


Unlike the other data entry fields, the value of the selected button is not returned by the binding of a 
variable given in the format descriptor. This is because clicking on a button usually terminates the 
dialogue. The value of the selected button is returned as the binding for the last bucton argument 
of the dialog call. This value is the position of the format descriptor for.the selected button 
within the entire format list of the dialog call. Note the comments above about the special role 


for Ok and Cancel buttons. 


(See the chapter on Advanced Dialogues for a description of the extended dialog call in which 
clicking on a button may not necessarily termunate the dialogue.) 
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4. check (down_pos,in_pos, depth, width, label, 
initial value, final value) 
This creates a check box field within the dialogue, of the size and position specified. The depth 
and width size of the field must be large enough for the check box and its adjacent label which is 


written to the right of the box. The label is any atom. 


The final value must be a variable. It will be bound to on or off indicating whether or not 
the check box was in the selected state when the dialogue was read. 


The initial value is one of: 


on The check box is displayed initially selected with a cross in the box. 
off The check box is displayed initially unselected. It is an empty box. 
S: radio(down_pos,in_pos,depth, width, label, 


initial value, final_value) 


This creates a radio button field within the dialogue of the size and position specified. The depti 
and width size of the field must be large enough for the radio button and its adjacent label which 
is written to the right of the button. The label is any atom. The radio button is a circie. 


The final value must be a variable. It will be bound to on or c== indicating whether or not 
the button was in the selected state when the dialogue was read. 


The initial value isone of: 
on The radio button is displayed initially selected with a dot in the circle. 
GEL The radio button is displayed initially unselected. Itis an empty circle. 


NOTE The radio button formats of a dialogue format list must appear on the format list in groups 
of adjacent format items, each such adjacent group being separated from any other adjacent group 
of radio buttons by at least one non-radio button format descriptor. (The radio buttons of each 
adjacent group should also be displayed in the dialogue box as adjacent fields so that they are 
interpreted as a group of alternative buttons by the user.) 


A radio button format must not be the last format descriptor of the format list. The group of radio 
button formats in the list must always be followed by at least one other different format item. 


If you only want to have OK and Cance! buttons (which must be the first two formats of the 
format list) and radio buttons in a dialogue, then follow the radio button formats with a dummy text 
field format which displays the empty string ". 


Unless the user uses a shift click, only one radio button of each adjacent group can be selected at 4 
time. Normal clicking on a radio button selects that button and deseiects any other selected rac:o 
buttons in the adjacent group of buttons. Shift clicking on an unselected radio button selects that 
button and leaves selected any other selected radio butttons. A selected radio button can be 
deselected without selecting any other radio button by shift clicking on the button. 


143 


17 : Dialogue Building 


6. icon(down pos,in_pos,depth,width,icon_id) 


This displays an icon of the size and position specified. The icon_id must be an integer 
identifying the icon. 


Some icon ids that you can use, and the corresponding icons are: 


0 A rectangle containing a profiled speaking face on the left with a ! mark to the right. 
: A rectangle containing a profiled speaking face on the left with a * mark to the right. | 
2 A rectangle containing a profiled speaking face on the left with a ? mark to the right. 


2003 A hexagon with STOP written in it. 


(These are icons defined as Resources in the Macintosh System. Their appearance may vary 
according to the version of the System you have on your Mac.) 





See the chapter on Advanced Dialogues if vou wish to use your own icons. 
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DISABLING ITEMS 
disable(field descriptor) 


Fields of type button, check or radio may be disabled by adding the modifier disable to 
their field format descriptor. The dialogue field is displayed ‘greyed out and cannot be selected or 
have its value changed by the user. This is useful for removing certain options on particular uses 
of the dialogue. For example, 


disable (button (50,50,20, 90, ‘Continue')) 


describes a disabled Continue button which would appear in grey in the dialogue. 


EXAMPLES 


l. dialog('',50,60,120, 370, 
[button(90, 10, 20, 60, ‘'Ok'), 
pbutton(90,290, 20, 60, Cancel]; 
text(10, 10, 32,350,wseq([‘Exter any zezm:'))), 
edit(45,. 10, 32,350; '"';reacizermi y] 
Btn) 


f 


This is the call that implements the single argument call to the pnminve zaa. 


EE TE E ite ee eee zoari pe ley Ue Cee bot t Bt ge 4% 
oe aata APEA n, H diiz ta 7 , Ae 5 eee ae y: a ab ef x > eee asx 
ce Ree PRR TT oS eg he ee a GA 


? > a ta 





Enter any term: 


in this case the dialogue window has no title. It has just two buttons ‘items 1 and 2 on the format 
descriptor list), a text field, and an edit field into which the user will type a term. 


If the user clicks on the Ok button, Btn will have the value 1 and the the term typed into the edit 
field will be returned as the binding for the variable Terz- 


If the user clicks on the Cancel button then the dialog call will fal. 
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2. dialog('Operator declaration',50, 80,140,370, 

sutton (1ii0,. 10; 20; 60, "OR" ); 

buttonii1e. 80, 20, 6C;, Cancel"), 
editi 5,790, 16,160," *,0p)., 
radio( 45, 10, 20,130,'left associative’,off,Left), 
radio( 65, 10, 20,130, ‘not associative',on,Not), 
radio( 85, 10, 20,13¢,'right associative',off,Right), 
edit( 30,315, 16, 25, '900',read(Prec)), 
check( 45,150, 20, 7°,vorefix,ctf,Pref), 
eneck( 655250, 20; 7opintié, 622, Inti, 
Sneek t-85.250,. 20. PC epOSttix; Olt; Posty, 
text ( 30,225, 16, £5, 'precedence:'), 
text( 5, 70, 16,11C, ‘operator name:')], 

Ben) 


This is the call which displays the operator declaration dialogue in response to the New 
operator... menu command of the programming environment. 


The variabies Op, Left, Not, Right, Prec, Pref, Inf, Post, andBtn wil] all be 
bound by the call. 





E a iv oe TOR e S aaar ea Ce eT ae 
‘“VDperitordectardtion +: eo StS 


a 
got t= 
ta 


precedence: 


O left associative [] prefix 
@ not associative [infix 


O right associative [] postfix 


Notice that the precedence: edit field has its initial value supplied as the atom "900" 


whereas the operator name: edit field is initialised to the empty string. The ‘labels’ for these 
edit fields are actually separate text fields. 
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17,2 mdialog - display and read from an unlabelled modal dialogue 


mdialog(down_pos,in_ pos,depth, 
width, format list, button) 


ARGUMENTS 
down _pos : integer, position of top of dialogue as a number of pixels down 
from the top of the Mac display 
in_pos : integer, position of left of dialogue as a number of pixels in from 
the left of the Mac dispiay 
depth : integer, depth of the dialogue in pixels 
width : integer, width of the dialogue in pixels 
format list :listof dialogue field format descriptors 
button : variable, will be bound to an integer inc:cating 
: which button was selected 
USE 


Almost exactly the same use as dialog. The difference is that the displayed dialogue box °s 
completely rectangular and is unlabelled. It must also be responded to before anything else is done. 


FORMAT DESCRIPTORS 


All the format descriptors allowed in a dialog call can appear on the format list for en mdia tz: 
call. They have the same effect and there are the sare constraints on their use. In addition, on 
other format descriptor is allowed. It describes a scroLing menu sud‘ce! 


menu(down_pos,in_pos,depth,width,item_list, 
preselected, selected) 


This describes a scrolling menu subfield of the size end position specified. (Only one such menz 
may be specified for any dialogue.) 


The dept of the menu must be the integer 16*n-2 where n is the number of atoms that wil: 22 
on display in the scrolling menu at any time. 


The extra arguments are: 


item list : list of atoms 

preselected  : listof atoms, sublist of -tem_lisc 

selected : variable, will be the list of user selected items from the menu 
The atoms displayed in the scrolling menu will be the atoms in icem List. 


The atoms in the preselected list will be shown as initially selected, i.e. will be in reverse 
video. (The preselected list may be empty.) 


The user selects an item by clicking on it. By holding cown the shift key whilst clicking, more than 


one item may be selected at a time. Items are deselected by clicking on them again. 


When the user presses the Ok button the selected list will be the list of selected items. 
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EXAMPLE 
The following call creates the modal dialogue shown below. 


mdialog (60,100, 90,300, 

[button ¢ss;,.10, 207 20." OK) 5 

Hutton (Ss... B0; 207 SS Cancel"), 
text(10, 10, 20,145, wseq({'Choose someone'])), 
menu (10,155, 66,140, 

‘SClijve’,. Tinky". PRil; "Clare"; Diane’, Frank- Ja 

:'Nicky'],Selected}))], 

gon). 






Choose someone 


í Cancel | 





‘Clare 


Notice that the depth of the menu is 66 which is 16*4-2, and thus 4 items are displayed in 12 


menu fielc. The remaining two list items (‘Diane' and 'Frank')can be displayed by click: - 
on the scroll bar. 


The user's eventual selection will be returned as the list Selected. 
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18 Advanced Dialogues 


This chapter describes some of the more advanced features of MacPROLOG's dialogue handling 
facilities. 


MacPROLOG supports the use of picture items in dialogues. Buttons and check boxes may be 
declared to be picture items. In the case of picture check boxes, there are also various ‘selection 
modes’ which can be specified, which determine the appearance of the item in its selected state (1.¢. 
when the user has clicked on the item). The pictures can either be created using MacPROLOG 
Graphics, or they can come from resource files. 


It is also possible to associate with any dialogue a goal, and for the dialogue to terminate only on 
successful completion of that goal. This can be useful in data entry applications, for example 
where the dialogue in which the user enters data stays on the screen until it is correctiy completec 


‘ 
we. 


In this case the dialogue's associated goal would perzcrm checks on the entered information, gis 


suitable messages, and, if necessary, modify the cia!ogue, until all the data was complete anc 
correct. 


There are primitives setditem and mcvediter. which change the appearance of a dialogue 
while it is on the screen - dialogue items may be repositioned, enabied or disabled, re-labellec cr 


even removed altogether, without terminating the cizogue itself. The primitive ge= <item retums 
the current status of any dialogue item. 


It is assumed that you have read the chapter on Diaicsze Building, which describes how to setup a 
general modal or modeless dialogue. 


18 : Advanced Dialogues 


18.1 Picture Items 


In addition to the edit, text, button, check, radioandicon dialogue items 
described in the Dialogue Building chapter, there are the picture item types pbutton anc 
pcheck. 


Their field format descriptors are as follows. 
18.1.1 pbutton(down_pos,in_pos,depth,width, pict_descr) 


This creates a picture bution field within the dialogue, of the size and position specifiec. 
(Remember that the down ros andin_rccs pixel values are relative to the dialogue window’. 
The button is displayed, without a label, as the picture given by pict_descr. 

The item behaves exactly lixe an ordinary button - when the user clicks on it the picture is displavec 
in reverse video, and its position in the format list is returned as the binding for the butter 
variable in the dialog call. 


Picture descriptions are fuliy expiained in the chapters on Graphics. However, if you have pictures 
in resource files then pict _ descr can be of the following form 


resource (name) 
or resource (name, file) 
OT resource (name, file, vol) 


where name is the picture name, file is an optional argument specifying the resource file, anc 
vol an optional argument giving the file's volume id. 


If file and vol are not given, the resource files that are currently open will be searched. If fiie 


is given, the file will be opened if necessary. If vol is not given, the current default volume is 
assumed. 
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18.1.2 pcheck(down_pos,in_pos, depth, width, 
mode,initial value, final value) 


This creates a picture check box field within the dialogue, of the size and position specified. A 
picture is displayed instead of the usual check box and label, but the item behaves exactly like a 
normal check box. If the user clicks in the picture it becomes selected; clicking again will deselect 
it. 


A picture description must be given to specify the appearance of the check box in its unselected 
state. There are various ways of displaying the check box in its selected state - the moce argument 
specifies the unselected picture pict_descr and the selection moce of the check box. 


The mode argument must be one of: 


frame (pict descr) The picture will be framed when it is selected. 

exOSs( pict. gescr) The picture will have a ‘check box cross’ (as in an ordinary 
selected check box) drawn over the top when selected. 

outline (pict descr) An attempt will be made to outline the picture's elements in bole 


(this only works weil if the picture contains one or two simple, 
clearly defined objects) when 11 is selected. 

invert (pict_descr) ‘The picture is ‘inverted’ on selection, 1.e. displayed in reverse 
video. 

switch (pict_descr, pict_descré) 
In this mode a second picture description must be given, and 
when the item is selected the seconc picture is disp:aved instead 
of the first. Clicking on this second picture deselecis the item 
and the first picture will be displayed again. 

overlay (pict descr, pict desc 2) 
In this mode a second picture description must be ziven, and 
when the item is seiecied the secona picture 1s Grawn on top of 
the first. 


The final value must be a variable. It will be bound to on or <== indicating whether or not 
the picture check box was in the selected state when che dialogue was read. 


The initial value is one of: 


on The check box is displayed initiaily selected. 
oft The check box is displayed in:aally unselectec. 
18.1.3 Icons 


If you have your own icons, they may also be used in dialogues. The format descriptor is of the 
form 


icon(down_pos,in_pos, depth, wi2th,1con_sescr) 


where icon descr takes the same form as a resource picture description, described above. (See 
the Graphics chapters for more details). 


151 


18 : Advanced Dialogues 


18.2 Extended Dialogues 


A call to dialog or mdialog may be extended to include an extra term which specifies a goal to 
be associated with the dialogue. Whenever a button other than the Cancel button is clicked on, 
control is transferred to the goal specified. If the goal succeeds, the dialogue terminates. If the goal 
fails, the dialogue remains displayed and control returns to the user to complete or modify the 
dialogue entries. 


The extended call takes the form 


dialog (title, Zown_pos,in_ pos, depth, width, 
format list, button, goal) 


where the arguments titieto button are as described in the Dialogue Building chapter. The 
format_ilist may of course contain picture items. The call to m¢ialog can be similarly 
extended with an extra goa- argument. 


The goal argument must te 2 term of the form 
test (€3,4p,++-,Gy) 


where test is defined as a «-2-ary relation. This is because it will be called by the dialogue 
handler with two extra arguments which will be the dialogue ID and the number of the button 
pressed. 


Whenever the user clicks on 2 dialogue button other than the Cancel button, a call is made to 


test (dlg, bt, 8189r- --r8k) 

where d1g is the dialogue ID, and btn is the number of the button that was pressed. (These values 
may be used if you want to call getditem, setditem or moveditem within the test 
program - see below). If the call to test succeeds, the dialogue terminates. If the call fails, contro! 
returns to the dialogue - the dialogue remains on the screen and the user must take further action on 
the dialogue. 


(Note that goal is only executed when the user clicks on a button other than the Cancel button. 
Actions such as clicking on radio items or check boxes, or entering text into an edit field, will not 
cause goal to be executed. } 


When goa1 is called, all variables in the format descriptors will have been instantiated. For 
example if the dialogue contains a check box field, the final val ue variable of its format 
descriptor will be either c ££ or on, reflecting the current state of the check box. So the arguments 
&1,8>,+++,a, Of goal can be output variables of the format descriptors, thus passing to the 
test program the current field values of the dialogue. However, the field values can also be 
accessed from within the test program using the getditem primitive. 


152 


18 : Advanced Dialogues 


18.3 getditen - get information on a dialogue item 


getditem(dlg,item, type, abled, setting, value, rect) 
ARGUMENTS 


dlg : integer, dialogue ID (inherited from call to dialog or madialog) 
item : integer, the dialogue item number 

type . : variable. Becomes the item's type 

abled : variable. Becomes either enabled or disażled 

setting : variable. Becomes either on or off or nuli 

value : variable. Becomes the item's value 

rect : variable. Becomes the item's enclosing rectangle 


USE 


This call is used to return the current status of any dialogue item. The item's parameters may be 
changed by calling setditem or moveditem - see below. 


The dig argument is the value passed by the dialogue handler (see c:scussion above}. 


The item number is the position of the dialogue item in the format ist as specified in the original 
dialog or mdialog call (see the Dialogue Building chapter). 


The type argument is instantiated to one of the following atoms corresponding to tne stems type: 
Sqit. text wurcen: pbutten. checks wcheck 22220- LOEn 


The abled argument is instantiated to one of the atoms enables or cisaklec. cepending on 
the current status of the dialogue item. 


The setting of the item is instantiated to one of the atoms cr. or cif if the item is a button. 
check box or radio; or to the atom nuit if the item is of any other tre. 


The value argument returns the item's value according to the items type., as follows: 


edit the textual contents of the edit field. as an atcm 

text the item's text, as an atom 

button, checx, or radio 
the item's label, as an atom 

pbutton the item's picture description 

pcheck either a single picture description or a list of two picture descriptions, 
depending on the mode specified in the dialzz or mdiacs call 

icon the atom nuli 


The rect argument is instantiated to a term of the form 
box (T, L, D, ¥) 
where T, L, D and W are integers: T and L represent the position of the top left corner of the item 


as numbers of pixels from the top and left of the dialogue, and D and 7 give the item's pixel depth 
and width respectively. 
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18.4 setditem - set a dialogue item 


setditem(dlig, item, reset) 


ARGUMENTS 
dig : integer, dialogue ID (inherited from dialog or mdialog call) 
item : integer, the dialogue item number 
reset : term representing the item's new Status 

CSE 


This call resets a dialogue item's status. The call may only be used to reset one parameter at a time; 
nowever, several calls to sex ditem may be made for any one dialogue item. To change an item's 
position, use moveditem. 


ne reset argument may take the following forms (some are appropriate only for certain types of 
c:alogue items). 


enable The dialogue item 15 enabled. 

fisable The dialogue item 1s cisabled. 

oo The dialogue item is set to on, 1.e. it is selected 

2r The dialogue item 1s sei to off, 1.e. it is deselected 

toggle The item is set to cz if it was of £, or to off if it was on. 

220M The item's text is changed to atom (e.g. may be the label of a button, 
or the contents of 2 text or edit field) 

zicture The item's picture cescription is changed to picture. 

“161,062, The item's two pictures are changed to picl and pic2. 


NOTE The ‘seiection mode’ of a picture cialogue item cannot be changed. Thus for example the 
‘sicl, pic2: form of the reset argument is only appropriate for a picture item with a selection 
mode of either switch or overlay. 
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18.5 moveditem - reposition a dialogue item 


moveditem(dlg, item, rect) 


ARGUMENTS 

dig : integer, the dialogue ID 

item : integer, the dialogue item number 

rect : term representing the item's new position 
USE 


This call repositions the specified item in the dialogue dig. 
The rect argument must be a term of the form 


boxitT bel 


where 


is the position of the top of the item as a number of pixels from the top of the dialogue 
is the position of the left of the item as a number 2f pixels frem. cre left of the dialogue 
is the pixel depth of the item 
7 is the pixel width of the item 


Ly bt ky 


PRAGMATICS 

A dialogue ‘:2m may be muce invisible by speci ini . new posne wien ts T E ew 

window. For example, if 122 dialogue window ts 144 mixeis deen nc 200 pixels wice. ne ci. 
scopo tem. oS bear OORT ele oe ow 


will make the Izem disappear. Sor instance, this may 72 Cone insi2ac of disabling an iem 


we te he 
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EXAMPLES 


Two simple examples of the use of extended dialogues are given below. 


Example 1 


The first example displays a dialogue asking for two integers. The program are ints simply 
checks that they are integers, and beeps and gives a warning message if they are not. 


readints (11,12) :- l i 

dialog('Integers',200,¢0,120,170, 

[putton (90, 20, ‘20, beo,*0k"). 

button(90, 90, 20, €°¢, 'Cancel'), 
text (10, 10, 32,15¢,*seq(["Enter two integers:*:)), 
edit(45, 15, 16, 5.,'',read(Il1)), 
edit (45,105, 26, Ecay ",;readtiz)} ly 

Btn, are ints(I1,12)). 


integer (Inti 


eve anes (D; B; Intl; Ines 
= q 
integer (Intz 


E 
TEE 
sre inte (D; B Intl; 2272) = 
beep (10), 
message('You must enter integers'), 
Tail; 


The initial dialogue displayed is 


i) 





If the user clicks on the Ok button and the two entries are not integers, the warning message is 
displayed. Note the explicit call to faii after the call to message, to ensure that control returns to 


the Integers dialogue window. 
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Enter two integers: 














O You must enter integers 


When the user has entered two integers, are ints wiil succeed and the dialogue will terminate. 


Example 2 
In the second example read day, the contents of the edit field is extracted in the checking 
program is da, by acall to getditem. 


read _day (ray) i~ 
dia_ca('weeka 7200; 60712072 3 
[Hatton oC, 20,20, 60; TOKT]; 
buston(90790;20; 60;TCancel?:; 
[exe (10; U0; 32r 150; bi ata Nees ene: cae heyy; 
e422 (45,207 16; 140, Monday t-87] a 
Bea, is dav): 
is day(D,5):- 


ge=s-cem(D, 4) Ype, Abled; Set, moon secs 
on (atom, ['Monday'’, 'Tuesday', 'weanesday 
‘Thursday', 'Friday', 'Sacurday', 'Sunday']),!. 


5-day (D;2)i= 
been (10), 
message('That is not a day of the week''), 
fail. 


In this case the edit field is prefilled with the atom 'Mez day ' 
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cS Miileekday: 0. <4 


Enter the day: 





If the user types anything not on the list of the days of the week and clicks on the OK button, a 
warming Giaiogue will be cisplayed, as in tne previous example. 


(Of course whenever the user can only enter one item from a fixed list, as in this example, it is 


better to present the user with a scrolling menu of the items, rather than ask them to type into an edi: 
field.) 
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19 Window Handling 


In this chapter we document the various primitives for creating and manipulating windows. These 


primitives are used to implement most of the commands of the Windows menu of the 
programming environment. 


There are extra primitives for manipulating graphics windows documented in the chapters on 
Graphics; however, many of the primitives in this chapter may be used for all types of 
MacPROLOG windows. 


Windows may be of the following types 


prog fora program edit window 
iisp fora display window 
info for an information window 
p fora graphics window 
clip forthe clipboard window 


19.1 wereate - create a display window 


wereate(name,visibility, down _pos,across_ pos, 
depth, width) 


ARGUMENTS 
name : atom, name of new window 
visibility : integer, either 0 or i 
down pos - t integer. position of top of window as number of pixeis 
down from the top of the Mac screen 
across pos : integer, position of i2ft of window as number of pixeis 
in from the left of the Mac screen 
depth : integer, depth of window in pixels 
width : integer, width of window in pixeis 
USES 


Creates a new display window (i.e. a window of type disp) with the given name and position. If 
the visibility is 0 then the new window is initially hidden. If itis 1, the window is visible. 


You can read and write to this window using the window I/O primitives. No attempt is made to 
compile the contents of a display window, so there is no associated syntax or mode. 
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19.2 wpcreate - create a new program edit window 


wpcreate (window name, visibility, syntax, mode, 
down _pos,across_pos, depth, width) 


ARGUMENTS 
window name : atom, name of the window 
visibility : Integer, either O or 1 
syntax : atom, syntax of window. Must be one of: 


'<EDINBURGH> ' for Edinburgh syntax 

'<USER1>' for an optional user defined syntax 

'<USER2>' for another optional user defined syntax 
mode : atom, giving compilation mode. Must be one of: 

'<COMP ILE>' for a Compiled window 

'<INTERPSRET>' for an Interpreted window 

'<DATA> ' for a Data window 

'<OPTINMISE>'for an Optimised window 


down pos : integer, position of top of window as number of pixels 
down from the top of the Mac screen 

across pos : integer, position of left of window as number of pixels 
in from the left of the Mac screen 

depth : integer, depth of window in pixels 

width : integer, width of window in pixels 


USE 


This call creates a new program edit window (a window of type prog) with the given name anc 


position and the associated syntax and mode. (The NeW... command of the Windows menu iz 
the programming environment calls wpcreéze). 


If the visibilityis 0 then the new window is initially hidden. If itis 1, the window is visibie. 


The syntax specifier is the name of the compiler that will be used to compile the contents of the 


window when you use the Check Program command in the programming environment. (See 
also the description of the windows primitive below.) 


User Defined Syntaxes 
If you create a window with <USER1> or <USER1> as the associated compiler you must define 
this relation yourself. The compiler is called with two arguments. The first is the name of tne 


window and the second is the atom which is the mode associated with the window. You shou.c 
define it in the form: 


'<USER1>' (Window, Mode) :- 


cursor (Window, Front,Back), /* find position of cursor * / 

cursor (Window, 0, .0), /* move cursor to beginning of window * / 
compile window(Window,Mode), / *recursive read/compile of window clauses” / 
cursor (Window, Front, Back). /* re-position cursor * / 


The compile window program should use the window I/O primitives to read in the clauses of 
the window. It must then transform these into normal Edinburgh syntax clauses, perhaps using the 
Mode argument to select a special form of transformation, before adding them to the interpreted 
database using assert. 
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If you want to extend the programming environment so that new windows with syntax type 
<JSER1> or <USER2> can be created by a menu command we suggest that you add a new menu 
using the install menu primitive which has a command that displays a dialogue with an edit 
field to find the name of the new special syntax window, and perhaps a pair of buttons to select the 
<JSER1> or <USER2> type (to which you can give more user friendly names). The command 
should then create the new window in some fixed position and of a fixed size using the appropria‘e 
wocreate call. 


(See the chapter on Implementing an Application for details of how this modification of the menu 
bar can be made automatic on the loading of an application program.) 


19.3 wtype - get type of a window 


wtype (name, type) 


ARGUMENTS 
name : atom, name of a window 
type : atom or variable 

USES 


To find the type of a window, type must be a variable - it will then be bound to one of tne 
following atoms: 


prog for a program edit window 
disg for a display window 
inro for an information window 
gran for a graphics window 
elip for the clipboard window 
If wcype is called with the type argument as one of the above atoms, the call succeeds if 122 


named window is of this type, or fails otherwise. 
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19.4 wsyntax - find the associated syntax and mode of program window 


wsyntax (name, syntax, mode) 


ARGUMENTS 
name : atom, name of a window of type prog 
syntax : variable, will be bound to one of the atoms: 


'<EDINSURGH>' for Edinburgh syntax 
'<USERi>' for an optional user defined syntax 
'<USER2>' for another optional user defined syntax 

mode : variable, will be bound to one of the atoms: 
'<COMPILE>' for a Compiled window 
'<INTERPRET>' for an Interpreted window 
'<DATA>' for a Data window 
'<OPTIMISE>' for an Optimised window 
Use 


To find the associated syntax and mode of a named program window. The syntax and moze 
arguments must be variabies. They will be bound to atoms giving the syntax and mode. 


19.5 wochg - check if text of a program window has been changed 
wchg (name) 


ARGUMENT 


name : atom, name of window of type prog 


USE 


The call succeeds of the window has been edited since the last use of wclchg or since the window 
was loaded. It tests a flag which is set when the window is edited. 


It is useful if you are implementing your own programming environment, and you want to define 
the equivalent of Check program. (See the description of windows below.) 


19.6 welchg - clear the edit flag for a window 


welchg (name) 


ARGUMENT 


name : atom, name of window of type prog 


USE 


Clears the edit flag that is set when the text of a window is edited - the flag is tested using wchg. 
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19.7 wrename - rename a window 


wrename (old name, new_name) 


ARGUMENTS 
old name : atom, name of a window 
new name : atom, new name of window 
USE 


To rename a window from old_name to new_name. 


19.8 wsearch - search for text in a window g 


wsearch (name, string,start, from, to) 


ARGUMENTS 
name : atom, name of a window 
string : atom, text to be found 
ster: : integer, character pos:tion for start of search 
fees. : variable, will become integer giving stant position of found text 
tc : variable, will become integer giving end position of found text 
LSE 


To search for the occurrence of some sequence of characters in a window. The window shouic = 
Ol type pros. Sisp or iz sc. 


The sequence of characters are given as an atom in the soring argument. 

= Spore : j SP ative tg th nem ats : pee ee 
The start argument is the characte: position (relative to the start of the window) from which 0 
commence the search. If this is given as 0, the search sians at the be zimning of the window. 


If the sequence of characters is not found, the call faiis. If it is found. variabie from becomes i^e 


character position of the start of the text and the tc variable becomes the character position of i22 


end of the text. These values can be then used in a call to the curscz primitive to highlight the 
found text. 
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19.9 cursor - find position of, re-position, or change appearance of cursor 


cursor (window, from, to) 
cursor (newcurs) 


ARGUMENTS 
window : atom, name of a window 
from : variable or integer 
tc : variable or integer 
newcurs ; atom 

USES 

1. Three ercument form 


The three argument form of cursor is used to find or reposition the text cursor in a window. The 
window should be of type srog, disp or info. 


To find the position of the cursor within a window the second and third arguments should be 
variables. from will then be bound to the character position of the start of the cursor and to will 
be bound to the character position of the end of the cursor. They will have different values only if 
the current cursor position 1s a selection range. 


To re-position the cursor all arguments must be given. The cursor will become a selection range if 
fromand =c have different values. 


A negative integer given as the value of from or to specifies the end of the text in the window. A 
value of 0 specifies the beginning of the text. The to value should be greater than (or equal to) the 
from value when they are both positive integers. 


The call 
cursor (window, 0,-1) 
will select the entire window (the cursor extends from the start to the end of the window's text ). 


2. One argument form 


The single argument form is used to change the visual appearance of the mouse cursor. The cursor 
retains its new appearance until another call to cursor or it is changed by the underlying system 
(for example the cursor automatically beomes a watch during some system processes). 


The newcurs argument must be one of the following names of predefined cursors. 


arrow 

1 beam 

spy glass 
pen 

cross hair 
thick cross 
watch 
garbage 
spiit 

left thumb 
right _thumb 
up thumb 
down thumb 


the system's arrow pointer 

the text cursor 

a ‘magnifying glass’ 

a pen 

a CTOSS 

a large cross 

the system's wristwatch cursor 

the MacPROLOG "Hoover' garbage collector 
a thick vertical line 

a horizontal scroll bar's left hand pointer 
a horizontal scroll bar's right hand pointer 
a vertical scroll bar's upper hand pointer 
a vertical scroll bar's lower hand pointer 
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19.10 wsltxt - select text from a given character range in a window 


wsitext (window, from,to, text) 


ARGUMENTS 
window : atom, name of a window 
from : integer, beginning of text 
to : integer, end of text 
text : variable, will become an atom 
USE 


To read in the sequence of characters in a given cursor range. The sequence of characters in the 
range from to are wrapped up as an atom which becomes the value of vanable texc. 


PRAGMATICS 


Can be used together with cursor and wsearch to implement a command that searches for the 


next occurrence of the currently selected text in a wincow, i.e. to impiement the Find selection 
menu command of the programming environment. 


19.11 cut - delete from the cursor range in a window 
cut (window) 

ARGUMENT 
Wirow : atom, name of a window 

USE 


Text in the cursor selection range of window is deleted from the named window and placed in the 
clipboard. This corresponds to the Cut command of the Edit menx. 


If window is a Graphics window, the selected pictures will be cut and placed in the clipboard 
using the currently set clipboard format for pictures. This format may be set using the Defaults 
command of the File menu (see the chapters on Graphics). 
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19.12 copy - copy from the cursor range in a window 
copy (window) 

ARGUMENT 
window : atom, name of a window 

USE 


Text in the cursor selection range of window is copied from the named window and placed in the 
clipboard. If the cursor is an insertion point, this call does nothing. This corresponds to the COPY 
command of the Edit menu. 


If window is a Graphics window, the selected pictures are copied to the clipboard, using the 
current clipboard picture format (see the chapters on Graphics). 


19.13 clear - delete from the cursor range in a window ` 


clear (window) 


ARGUMENT 
window : atom, name of a window 
USE 


Text in the cursor selection range of window is deleted from the named window. It is not placed 
in the clipboard. This corresponds to the Clear command of the Edit menu. 


If window is a Graphics window, the selected pictures will be cleared. 


19.14 paste - paste into the cursor range in a window 
paste (window) 

ARGUMENT 
window : atom, name of a window 

USE 


Text in the clipboard is pasted into the cursor selection range of window, overwriting the text in 
the selection range. If the selection range is an insertion point, the clipboard text is simply inserted 


at that point. This corresponds to the Paste command of the Edit menu. 


If window is a Graphics window and the clipboard contains a picture, the picture will be pasted 
into the window, and its picture description added to that window's list of pictures. 
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19.15 undo - undo the last editing action 
undo (window) 
ARGUMENT 
window : atom, name of a window 
‘USE 


If window is the window in which the most recent text editing was done, the last ec:ting action 1s 
undone. This corresponds to the Undo command of the Edit menu. 


19.16 whide - hide a window 
whide (window) 
ARGUMENT 
window : atom, name of a window 
USE 
The named window is hidden. It can be made visible again using the «sr.ow primitive. 


Note that the contents of the window are preserved and vou can still read and write io the window 
using the window I/O primitives. 


19.17 wshow i make visible a hidden window 
wshow (window) 
ARGUMENT 
window ‘ atom, name of a window 
USE 


The named window is made visible if it was hidden. Otherwise, there is no change. ‘7indow does 
not automatically become the front window - you must use wfront to achieve this. 
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19.18 wfront - make a window the front window 
wfront (window) 
ARGUMENT 
window : atom or variable, name of a window 
USE 
If window is given, the named window is made the front window even if it was hidden. 


If window is a variable, the name of the current front window is returned as the value of window. 


(If the front window is the Default Output Window, the name returned will be ‘Default 
Output Window’, and not user.) 


19.19 wvis - test if a window is visible 

wvis (window) 
ARGUMENT 

window : atom, name of a window 
USE 


The call succeeds if the named window is currently visible, and fails if it is currently hidden. 


19.20 wkill - kill a window 

wkill (window) 
ARGUMENT 

window : atom, name of a window 
USE 
The named window is deleted. It cannot be re-displayed using wshow. The text of the window is 
lost, but the compiled relation definitions or interpreted clauses produced by compiling the window 
are not deleted. 


If window is a Graphics window all picture descriptions associated with the window are removed. 


If the window argument is not the name of a current window then wkill does nothing and 
succeeds. 
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19.21 wsize - get or set the size and position of a window 


wsize (window, down,in, depth, width) 


ARGUMENTS 
window : atom, name of a window 
down : integer or variable, the position of top of window as number of pixels 
down from top of the Mac display 
in : integer or variable, the position of left of window as number of pixels 
in from left of the Mac dispiay 
derth : integer or variable, pixel depth of window 
width : integer or variable, pixel width of window 
USE 


To find or set the position and size of a window. 
The windcw argument must be an atom, the name of a window. | 


Any or all of the remaining arguments may be varcbles: if so, they will be instantiated to the 
current values for the named window. 


Any or all of the remaining arguments may be integers: in this case the corresponding attribute o 
the namec window will be set to the given value. 


For exampie. the call 


m p m 


WelSe ("My N oraow"e Tos, Sere. 2.259 300) 


will set the size of the window 'My Window' to 22 200 pixels G22ep and 300 pixeis wide. Ti 
position of the top left corner of the window (which is unaffected by this call) is returned as th 


whe 


fu fy 


values of 722 and Left. 


The cal! 


4 


Wei cel "My Verdow'; Si, FO, CESSA sides: 
will position the window ‘My Windcw' 50 pixels trom the top anc 70 pixels from the left or : 


screen. The current size of the window (which is no: arfected by this call) is retumec as the values 
of Depth and Width. 
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19.22 windows - find all windows of a given type 
windows (type, window list) 
ARGUMENTS 


type : atom, either prog, disp, infoor grap 
window list :varable, will become list of window names of specified type 


USE 


Finds all the names of the windows, visible or hidden, of the given type. 


The primitive can be used to implement the equivalent of Check program as follows: 


‘Check progranm':- 


windows (prog, Wlist), | 

on (Window, Wlist), /* find a program window * / 
wohg (Window), /* has window been edited? * / 
wsyntax (Window, Svntax,Mode), /* get syntax and mode */ 
welchg (Window), /* reset its edit flag * / 

Syntax (Window, Mote), /* call Syntax compiler * / 
fail, /* backtrack for next window * / 


"Cneck progranm'. 


19.23 wont - font details for a window 


wfont (window, font, face, size) 


ARGUMENTS 
window : atom, name of window 
Tont : atom or venable 
face : integer or vanable 
Size : integer or variable 
USE 


To set or find the font details of a window. 


The font is an atom representing the fon: name, such as 'Chicago', 'Times', 'Couriez' 
or any other font supported by your system disk. 


The face is an integer representing the style of the text It may be 


Q Normal! 

1 Bold 

2 Italic 

4 Underline 
8 Outiine 
16 Shadow 


or the sum of any of these (to represent a combination of styles). 
The size represents the font size, and may be 10, 12, 14, 18, etc. 


If the font, face and size arguments are variables, they will be bound to the current details for 
the named window. 
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19.24 balance - check balance of brackets in text 


balance (window, from, to) 


ARGUMENTS 
window : atom, name of a window of type crea or disp 
from : variable 
to | : variable 

USE 


The current selection range in the named window is extended to include the next outer pair of 
matching brackets. The recognised brackets are 


Cd ok 2 0:3 


The variables fromand == are given the values of this new cursor s2.2ction range. 


This is the same as the Balance menu command of the programming environment. 


19.25 screen - find size of the Mac display 


screen(depth, width) 


ARGUMENTS 
depth : variabi2. will become ceoth of veur Mac display in pixels 
width : variable. will become width of vour Mac display in pixels 
USE 
To find the size of the screen of the Macintosh on wrich a program is running. On a Macintosh 


Plus the depth will be 3 2 and the w= 22h will bes: =. 
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19.26 cleanup - tidy up the screen window display 


cleanup (type,top,left,top_ incr, left_incr) 

cleanup (type,top,left,top incr,left_incr, 
depth, width) 

cleanup (type,top,left,top_incr,left_incr, 
depth, width, font, size) 


ARGUMENTS 
type : atom 
top : integer 
left : integer 
tep incr : integer 
left incr : Integer 

depth : integer 

width : integer 
font : atom, font name 
size : integer 

USE 


To rearrange on the screen all the windows of a given type. 


1. Five argument call 
The type argument is the window type, wnich should be one of 


ty 


4 oY 
Q 


Q Me'n 
tt | 
w u 
dU OW 


The tor and left arguments give the distance, in pixels, from the top and left of the screen 
respectively that the first window shoulc be placed. 


The top incrand left_incr arguments give the distance between the top left hand corners 
of successive windows. 


For example if top incr has the value 5 and left_incr has the value 8 then the top left hand 
corner of each window will be 5 pixels down and 8 pixels across from the previous one. 


2. Seven grgument call 
The first five arguments are as above. In addition, each window may be resized as it is replaced on 
the screen. The depth and width arguments give the new size (in pixels) for the windows. 


3. Nine argument call 


If the last two arguments are given, each window will have its text converted to the font font of 
Size size. 
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20 Resources 


MacPROLOG provides access to the Resource Management routines of the Macintosh. You may 
create resource files (or create a resource fork for an existing data file), and load and save resources 
from these and other existing resource files. The MacPROLOG Graphics language and Graphics 
primitives provide for extensive use of picture, icon and cursor resources. In addition, you may 
write code resources in either C or Pascal and call them directly from within Prolog. 


Further details on specific uses of the various resource types are given in the chapters on Graphics, 
Dialogues and the Pascal and C Interface chapters. 


20.1 Resource Items 


QuickDraw pictures, cursors, icons and other objects used by the Macintosh can exist on disk cs 
resource items in special resource files. 


Resource items have the following attributes. 


a) resource type 
There are many resource types. Those used in MacPROLOG are 


reir a QuickDraw picture 
To ON* an icon 
rcCURS' a cursor 


b) resource item number 
This is a number unique to that file, which can always te used to identify and access ine resource 
item within the file. 


c) resource item name 
This is the name for the resource item in the file. This may be the empty string ", especially for 
resource items created outside of MacPROLOG. 


d) resource file name 

This is the name of the resource file. Resources can +e associated with existing program files. -s 
these files can have two forks’: a dara fork (where your trogram is stored) and a resource fork tor 
your resources. | 


e) resource file volume 
The volume ID where the resource file resides - this c2n De found using the old pnmiuve. 
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20.2 Using Resource Items in MacPROLOG™ 


A resource item cannot be loaded until its resource file has been opened. The MacPROLOG™ 
application resource file will always be open, as will the System resource file. 


Generally, when resource items are first accessed in MacPROLOG the named resource file in 
which they are stored is automatically opened. Where a primitive has optional arguments for a 
resource file name, you only need to supply this information if the file is not (or may not be) 
already open. However, vou may sometimes need to open resource files explicitly with the 
res open primitive, described below. 


When a resource file is first opened, a copy of its 'memory map’ i.e. a list of the resources that are 
in that file, is stored in memory. When memory is tight. these memory maps can be removed using 
res close. 


You can get a list of all resource items of a given type in currently open resource files by calling 
res items. 


When a resource is to be loaced, the Macintosh Resource Manager searches through all the open 
resource files. searching the most recently opened files first. Once a resource item is in memory, 
any subseavent uses of it are very fast. You can delete a resource item from memory if you have 
finished with it and are running short of space, using -¢s_ finish. Then if you need the item 
again it will be reloaded from disk. 


Individua! resource items mav be loaded and used by caliing specific primitives. The following are 
some of the primitives you my use; they are fully documented elsewhere. 

Resource pictures can be accessed using the Graphics Description Language (GDL) picture 
descriptor and the pbutzcr. or pchec» dialogue format descriptors. They can be created and 


saved to disk using save_=-c. 


Resource icons can be accessed using the GDL icon descriptor and the icon dialogue format 
descriptor. 


Resource cursors can be accessed using acursor. 


Code resources may be loaded and run using the cal1_c and call_pascal primitives. 
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20.3 res create - create a resource file 
RaT P 7 

res open (file) 

res open(file, volume) 
ARGUMENTS 

file : atom, name of resource file 

volume : integer, volume identite 
USE 


To create a narned resource file. 


If file does not already exist, it will be created. initially with an empty resource ‘ork and =~ 
empty data fork. 


If file already exists but has no resource fork, a resource fork wiil be created for tie:cile. 

If file already exists and has a resource fork, then zsz_create does nothing. 

res create does not open the file - to do this you must call res_oren. 

PRAGMATICS 

A MacPROLOG program file initially has a data fork (where the program is stored) anc 7: 
resources. Thus if you call res create with an existing MacPROLOG program 1i. name, p1- 
can create a resource fork for that file. You can then ‘:ore resources (such as pictures, icons et. 
with the program. Because the data fork and the rescurce fork of a file are Jogically separate. =c 


can save a new version of the program to the file without affecting any resources you have alresz> 
saved. 
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20.4 res open - open a resource file 


res open (file) 
res open (file, volume) 


ARGUMENTS 
file : atom, name of resource file 
volume : integer, volume identifier 
USE 


To open a named resource file, thereby making all its resources accessible. 
(You don't ever need to open the System or the MacPROLOG resource file, since they always 
remain open). 


20.5 res close - close a resource file 


res close (file) 


ARGUMENTS 


fiie : atom, name of resource file 
USE 
To close a named resource file. Its resources are no longer directly accessible. 
If £226 is not the name of a currently open resource file then res_close does nothing and thz 


call succeeds. 


WARNING: Do not ever attempt to close the System or the MacPROLOG resource file, since 
they need to be open for access ali the time. 


20.6 res finish - delete a resource item from memory 


res finish (nameornum) 


ARGUMENTS 


nameornum : atom or integer, name or number of resource item 
USE 


To remove a resource item from memory. Use this if you are running short of memory, and the 
resource item (say, a picture) is large. Note that this will not close the resource file in which the 
item is stored, and you may still use the item, but any subsequent reference to the resource will 
generate a disk access to reload the resource item. 
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20.7 xres_items - return information on available resource items 


res _ items(res type,listofitems) 


ARGUMENTS 

res type : atom, resource type 

listofitems : variable, will be bound to list of resources 
USE 


This primitive returns information on all the resources of a given type that can be found in all the 
currently opened resource files. 


The res_type argument is a four character atom representing the resource type, for examp'e 

PICI Or ICON" 

Thelistofitems isa list of which each item is a three element list of the form 
fResourceName, ResourceNum, Fils. 

zesource?ame 1s an atom that labe!s the resource ::em. If for exempie it is a picture saved iz 

MacPROLOG by a call to save_pic it will be the name used in thatcall. Resources created ir 

other applications often have the empty string (" ) as :neir name: the. tend to rely on the resource 

number to idenufy the resource within a fiie. | 


ZescurceNum is a unique integer idenufying the resource item within that file. 


File is the name of the resource file. For resource items residing in the Svstem or in 
MacPROLOG, this file name will be system. 
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21.1 Introduction 


MacPROLOG™ allows you to write your own primitives in C and call them directly from within 
Prolog. The primitives must be compiled as separate code resources. and they are then loaded as 
they are needed by the Macintosh Resource Manager. This means that there is no need to rebuiic 
the LPA MacPROLOG™ application file, but you can create your own separate library of C 
routines which are callable from Prolog. The extent to which these new primitives behave like a 
program written in pure Prolog depends on how many of the primitive's uses have been catered for 
by the C programmer. 


A C primitive may have arguments passed to it from Prolog. There is a collection of interface 
routines which allow you to access tnese arguments and their values, and return values to Proles 
by binding the variables of the call. 


Like a Prolog program, a C primitive either succeeds or fails, possibly binding variables in the 
process. Unlike a Proiog program, however. the C primitive cannot be non-deterministic: that is. 
vou cannot backtrack into it to evaluate alternative solutions. If you want this behaviour, you c27 
write a Prolog program to sequence through non-deterministic solutions to your C pnmitive. 


Having written your new primitive as 2 code resource, it is called from within Prolog with the 
szall c primitive, which will load and run the specified code. Prolog arguments to the call mas 
pe accessed from within the C code. 


21.1.1 Requirements 


To use the C Interface, you will need the supplied library of Prolog interface functions, a C 
Compiler and Linker, and a 68000 Assembler. In particular, your C compiler must be able to 
compile functions which conform to Pascal calling conventions, since the interface functions are 
Geclared as "Pascal" functions (which corresponds to the MacIntosh Toolbox caliing conventions). 


Important Note 

LPA MacPROLOG™ was written using the MPW (Macintosh Programmers’ Workshop) package, 
and instructions for creating code resources here refer to MPW. If you use a different compiler. 
there may be differences in function calling conventions, and you may have to make some 
adjustments to the supplied source files or to the way in which you call the Prolog interface 
functions. See the Technica! Specification Section for further details. 
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21.2 Calling a C Function - An Outline 


Here we sketch the format of a C primitive and the method of calling it from Prolog. For a more 
detailed description, refer to later sections of this chapter. In particular, a complete example is giver 
at the end of this chapter. 


There is a file cxface. hed which contains the various function declarations needed to interface 
with Prolog, which should be included in your C source file. There is a compiled assemb!. 
language file xface .o which contains the function definitions, which should be linked with your 
compiled C code. 


When aC program 1s called from Prolog it will be called with two arguments. 


The first argument {argc in the example below) is an integer giving the number of Proic 3 
arguments to the call. (You can read these Prolog arguments using the gez_a=g Tuner es: 
descnbed later in the Term Access Functions section.) 


The second argument is a pointer to a routine in the MacPROLOG™ application code which t2 
various Prolog term access routines use. This second argument must be passed on to ee 
set link function (defined in the interface files) as the first function call of your C c0ce: 
thereafter this Link argument may be ignored. The sez_link function does the “gluing” osoa 
code resource to MacPROLOG™., 


The C primitive must retum a Boolean value (i.e. 0 or 1) correspona:ng to the pnmiuve SuccEes 2 
or failing. The interface file defines the type boo . and also defines TRUE and SVICESS to a 
equal to 1, and FAIL and FALSE to be equal to 0. 


Your C program will look something like this. 


zool mycprim (argc, link) 
int argc; 
void (*link) (); 


variable declarations etc. 
set link (link); 
if (argc != 3) 
return(FAIL); 


rest of program 


return (SUCCESS); 
} 


As described above, argc is the Prolog argument count. This paricular program is expecting > 
Prolog arguments, and it immediately fails if this requirement is noi met. The body of the progrem 
will make calls to the Prolog term access routines to read the three Prolog arguments, and to tne 
term construction functions which will bind any variables of the call. 


The C code must then be compiled and linked as a code resource (you may give it any resource tre 
and ID). It is then called from MacPROLOG using the call_c pnimuuve (see below). 
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21.3 call_c - load and run a C code primitive. 


call c(Ai,Apy,...,A,, Festype, resid) 
z e k YP 


ARGUMENTS 
AAD Ap : Prolog arguments to the C primitive 
restype : resource type of code resource 
resid : resource ID of code resource 


This call loads and runs a C routine in the code resource identified by the restype and resic 
arguments. The first k arguments to ca11_c will be placed in the Prolog argument registers for 
subsequent access by the C primitive. 


Note that the resource file containing the resource will nor be automatically opened by call_c: 
you should do this with a call to res_oper. before you call the code. 


The call_c primitive will succeed or fail depending on the SUCCESS / FAIL result passed back 


from the C program. call_c will also fail if the resource cannot be loaded for any reason. This 
would happen if, for example, the resource file was not open. 


EXAMPLE 


Suppose you have a C program in a code resource of type MINE and with ID 100, which expects 3 
arguments. If in Prolog you name this primiuve cprinm, then you would add the following clause. 


Sprim{A,; 5; C)-= 
call € (5, B, Gi "MIKE! P} 1930) . 


After you have opened the resource file containing your code resource ( by calling res_ open), 
corimcan be called just like any other Prolog program. 
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21.4 Storage of Terms in MacPROLOG 


In order to make use of the functions providing an interface to Prolog from your C program, ycu 
need to be aware of how terms are represented internally in MacPROLOG. You do not have to 
understand the exact memory formats, but you need to know the general structure of the different 
sorts of Prolog term and how they are stored. 


21.4.1 Tagged Cells 


A term in MacPROLOG is stored in a tagged cell. The tag of the cell indicates the type of data 
stored in the cell, and the rest of the cell represents its value. 


Access to these cells from C is always via cell pointers. The type ze1lpo is defined in the C 
interface to be a tagged cell pointer. 


All term manipulation is done by passing cell pointers to the various term access and construcion 
functions provided. You will never manipulate the tagged cells directly. 


The C interface provides a number of these term access functions which allow a C program to fine 
out about the term stored in a particular cell. For example, the gez_int_val function returns 122 
integer value of an integer cell. There are also a number of term construction functions which alico 
new Prolog terms to be built and returned as bindings for existing unbound variables. For examr.. 


the put list function binds a variable to a Prolog list structure. These functions are describec in 
more detail later. 


These term access and construction functions present a fairly abstract view of the MacPROLCG 
data structures, and therefore you need not be over concerned with the exact internal representat.on 
and memory layout of Prolog terms. 


21.4.2 Prolog Argument Registers 


A C function can access the Prolog arguments given in the call to c211_c. There are 31 Pro.og 
argument registers each of which can hold any Prolog term (i.e. a tagged cell). There may there:ore 
be up to 31 Prolog arguments to the C function which will be placed in these argument registe7s. 
The interface function get arg can then be used from within C to read these argumen:s. 
set arg will retum a pointer to the term cell in a specified Prolog argument register (see the [ens 
Access Functions section below). 
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21.5 Prolog Term Structures 


There are seven different term types in LPA MacPROLOG™. These are detailed below. As 
described above, each Prolog term is held in a tagged cell. The tag values (defined in the interface 
files) are as follows. 


TERM TYPE TAG 

Variable VARTAG 

Integer INTTAG 

Real REALTAG 

Constant CONTAG or STRTAG 
List LISTTAG 

Empty List NILTAG 

Tuple TPLTAG 


21.5.1 Variable 


A VARTES cell represents an unbound variable. Such cells may be bound to other Prolog terms 
using the term construction primitives such as put_int_val,put_con_text etc. 


21.5.2 Integer 


An INTTACT cell represents an integer, stored as a 24 bit signed value. Note that C uses 32 bits for 
integers. Dui integers outside the range -8388608 to 8388607 wili not be correctly represented 17 
Prolog. 


21.5.3 Real 


A REALTAG cell represents a floating point number. It is stored as an 80 bit value, which 
corresponds to the C data type extendec. 

(Note thet in MacPROLOG™ real numbers are automatically converted to integers if possible, se 
that when vou construct a real cell you may sometimes get an integer cell instead). 


21.5.4 Constant 


A CONTAS or STRTAG cell represents some text stored as a sequence of ASCH characters. The cel 
may have either of the two tags CONTA or STRTAS, which merely reflects whether the text is 
stored as a ‘permanent’ dictionary entry or as a ‘temporary’ object in the Prolog ‘heap’. The actuai 
format of the stored text is identical in each case. 
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21.5.5 List 


A LISTTAG cell represents a Prolog list structure. The list cell actually points to two more term 
cells, one representing the term at the head of the list, and the other representing the tail. The taii 
will usually be another LISTTAG cell, or the empty list (i.e. a NILTAG cell). 


For example, the Prolog list 
liG; Cate 2:5] 


is represented by a LISTTAG cell which points to an integer cell with the value 10, and another 
LISTTAG cell. This second list cell points to a constant cell with the value cat, and a third lis: 
cell, which in tum points to a real cell with value 2 . =, and a NILTAS cell. 


m ea — 


SaS PLAG 





INTTAG 









Thus the internal representation of the above list is 


[20; [cat, [2-5, []] 1 ] 


21.5.6 Empty List 


A NILTAG cell represents the empty list. As described above, one of its uses is as a tail cel. :9 
terminate a list. A NILTAG cell has no "value". 
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21.5.7 Tuple 


A TPLTAG cell represents a Prolog tuple structure. ‘A tuple is a fixed size array of elements, where 
each element is any Prolog term. This corresponds to the internal representation of a functor and its 
arguments. 


For example, the Prolog term 

FOOTOE ra] 
is represented internally as a tuple with four elements, the first element being a constant cell with 
value foc. and the remaining elements being integer cells with values 10, 20 and 3c. 
(\MacPROLOG also stores an extra "size" cell at the beginning of the tuple structure which gives the 


number of tunic elements.) 


The above wple therefore looks like this. 
















mm pa e : A ae a aan 
KE Loa t — E ee ST 
+ 





Since a tuple is a fixed size. it has a more compact representation than a list. 
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21.6 C Interface Term Access Functions 


These functions allow you to read Prolog terms from within C. As mentioned above, a Prolog 
term is stored in a tagged cell, but all term manipulation is done using pointers to these cells. 


All these functions are declared in the file cnface.ned (which you will #include in your C 
source file). 


Note that these functions will do no checking of arguments: you are responsible for ensuring that 
any arguments you pass to these routines are of the correct type. For example, if you pass a 


~=STTAG cell pointer to the function gez_con_texct, there is no guarantee of what the resu::s 
might be! 


The types cellro (a tagged cell pointer) and zea. fan 80 bit floating point AUmoer ero ccc are 
in the file cxface.hed. 


21.6.1 get_arg 


Ca opo get_arg (num) 

encerc num, 
Tas ; ` " ~ (Cro t r -e as m wr: = Feman 
This function returns a pointer to the cell in Prolog argument register num where mim ranges irem 


by 
- to arac (the Prolog argument count, passed as a parameter to your C tuncton). You may reac 
-se Prolog argument registers in any order. 
‘There is no guarantee that you will get anything sensioie if you try to read a register bevond ax 
The validity of num is not checked by gez_ arg.) 


~ 
- 


it] 


21.6.2 get_tag 


© get tagicp) 

po cp; 

This function returns the tag of a Prolog cell pointed to by cp. The value retumed will be one of: 
VARTAG INTTAG REALTAG CCNTAG STRIAG LISTTAG TILTAG TPLIAG 


_—_ i 


The tag indicates the type of the data stored in the cell. 
For example, 


get tag(get_arg(1)) 


will return an integer representing the type of the first Prolog argument. 


21.6.3 get_int_val 


int get_int_val(cp) 
cellpo cp; 


This function returns the integer value of an INTTAG cell pointed to by cp. As descnbed above. 
although a C int type is returned, only the lower 24 bits are used by MacPROLOG. (The integer 
returned by get_int val will have been sign extended to 32 bits). 
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21.6.4 get_real_ val 


real get_reai_val(cp) 
celipo cp; 


This function returns the real (floating point) value of a REALTAG cell pointed to by cp. The type 
real is an 80 bit floating point number and is defined in cxface.hed. 


21.6.5 get_con_text 


char “get corn .ext (si:27 cp) 
char “Str; 
cellpo cp; 


This function returns the text of either a CONTAG or STRTAG cell pointed to by cp. The text will 


be copied as a null terminatec string into the buffer pointed to by st x; this pointer is also returnec 
as the funcnon result. 


You must ensure that str points to a buffer large enough to hold the string; the maximum length o: 
a MacPROLOG™ constant is 255 characters. The get_con_text function does not allocate the 
space for vou. 


21.6.6 get _con_len 


pe ~get_corn_-en (cp) 
ce_ipo cp; 


This function returns the ciuli number of characters in the text of the CONTAG or STRTAG cell 
pointed to by cp. 
21.6.7 get list head 


po Gert -67 head(c5) 
-ipo cp; 


celi 
cei 
— = 


If cp points toa LISTTAS celi, this function returns a pointer to the cell representing the term at 
the head of the list. 


21.6.8 get_list_tail 


cellpo get_iist_tail(cp) 
cellpo cp; 


If cp points to a LISTTAG cell, this function retums a pointer to the cell representing the tail of the 
list. 
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21.6.9 get_list_len 


int get _list_ien (cp) 
cellpo cp; 


If cp points to a LISTTAG cell, this function returns the length of the list (i.e. the number of 
elements in the list). 


21.6.10 get_tpl_len 


ine. get tpl. Jenicp) 
Ce...00 cp; 


If cp points to a TPLTAG cell, this function returns the number of elements in the tuple. 


21.6.11 get_tpl_nth 


celipo get tpl nth(ntn,cp) 

Ere peN 

ceilpo cp; 
If sp points to a TPLTAG cell, this function returns a pointer to the cell representing the n15 
2'ement of the tuple. The first element of the tuple is numbered 1. The value of ntz should not 
2xceed the length of the tuple. 


187 


21 : C Interface 


21.7 C Interface Term Construction Functions 

The following functions allow you to construct new Prolog terms and to bind existing unbound 
variables to them. Each function expects to be passed a pointer to an unbound variable (i.e. a 

pointer to a VARTAG cell), which will then be instantiated to a new Prolog term. The function 

returns a pointer to this newly created term. 


In a similar way to the term access routines, no check is made that the cell pointer does in fact poir: 
to a VARTAG cell. 


These bindings will automaticaliy be undone on backtracking. 


You should not try to construct a new term in a cell which is not a variable, as this is not logical anc 
may lead to strange results. 


21.7.1 put_int_vail 
cellpo put_int_val(unb,vaél) 
celipo unb; 


int val; 


This function constructs an integer cell and binds it to the variable pointed to by unb. As mentionec 
previously, only the lower 24 bits of val are stored. 


21.7.2 put_real_val 


lpo put rea. val (unb, val) 


This function constructs a real cell and binds it to the variable pointed to by unb. As notec 
previously, if val can be expressed as an integer, an integer cell will be constructed instead. Thus 
tne tag of the constructed cel may be either REALTAG or INTTAG. 


21.7.3 put_con_text 


cellpo put_ccn_text (unk, str) 
cellpo unb; 
char *str; 


This function constructs a constant cell from the null terminated string pointed to by st r and binds 
it to the variable cell pointed to by unb. The tag of the returned cell will be either CONTAG or 
STRTAG. 


188 


21 : C Interface 


21.7.4 put_iist 


cellpo put_list (unb) 
cellpo unb; 


This function constructs a list cell and binds it to the variable pointed to by unb. Two extra cells are 
created, one for the head of the list and one for the tail. Both of these will be initialised to unbound 
variables. You can access these cells (and bind new Prolog terms to them) using the 
get_list_headand get_list_tail functions. 


21.7.5 put_nil 


celLlpo put_2-1(unb) 
ce Lpo unk; 


This function constructs an empty list cell (a NILTAS cell) and binds it to the variable pointed to by 
unb. 


21.7.6 put_tpl 


csiipo: pur. vol(unb, size) 
ce. 1po.-uEcr, 
ac. SiZe; 


This function constructs a tuple cell and binds it to the variable pointed to by unb. An amay of exwa 
cells is created for the size tuple elements. All of these will be initialised to unbound variables. 
You can access these cells'(and bind new Prolog terms to them) using the get_tpi nts 
function. 


21.7.7 put_copy_ cell 


celilpo put copy cell{(dest,src! 
ce loo. des .,S2.C; 


This function copies the term pointed to by src to the term pointed to by dest. The function 
returns a pointer to the dest term. 

The destination cell must be an unbound variable at the time of the call, but the source cell may be 
any Prolog term (including another unbound variable). If you use this function to copy one variable 
cell to another, the effect is to make both cells refer to the same variable, and binding one of these 
variables to a new Prolog term automatically binds the other variable to the same term. 
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21.8 Reporting Errors from a C Primitive 


If you wish to report an error from within your C code, you may call the function errortrap 
with an error code signalling the type of the error. 


21.8.1 errortrap 


void errortrap (errno) 
short errno; 


This function generates a Prolog numbered error. It does not return control to the calling routine, 
but jumps straight to the Prolog error handler. The error will be handled in exactly the same way as 
any other Prolog error. See the chapter on Implementing an Application for more details on error 
handling, and the Appendix for details of the error numbers available. 
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21.9 Creating a C Primitive 


NOTE This documentation assumes that you are using the MPW C Compiler, 68000 Assembler, 
and Linker. If you are using a different Compiler and Linker you may need to refer to your own 
manuals for specific instructions on creating code resources. 

See the Technical Specification section to determine what changes, if any, you may need to make to 
the C or Assembly language source code provided. 


To create a new C primitive for MacPROLOG you will need the files xface.o, cxzace.hes 
anduser.c. 


xface .o is an object code file containing the routines giving access to the Prolog data structures. - 
It is written in assembly language, and needs to be linked in with your C object code to create the 
final code resource. 

Note The source for xface.o is in the file xface.a, which you will only need to use if you 
find that the format of x£ace.o is not compatible with your Linker. In this case, you will need to 
assemble xface.a using an appropriate 68000 assembler (after making any necessary textucl 
changes to conform to your assembler’s syntax and other features), before linking the resulting 
object code with your C object code file. 


exface.hed is a text file to be included in your C source code file, user .c. It contains all the 
type and function declarations needed to interface with Prolog. 


user.c is a text file which will contain the source of your C pnmitive. 


21.9.1 The Format of a C primitive 
When aC program is called from Prolog it will be called with two arguments. 


The first is an integer giving the number of Prolog arguments to the call. (You can read these 


Prolog arguments using the get_arg function, described above in the Term Access Functions 
section.) 


The second argument is the pointer to a routine in the MacPROLOG™ application code which tne 
various Prolog term access routines use. All you need to do with this second argument is pass ii en 
to the set link function as the first function cail of your C code: thereafter you should ignore 
this "link" argument. The sez_link function does the “gluing” of your code to MacPROLOG *: 
if you omit to call set_1inx you can expect to have serous errors. 


The C primitive must return a Boolean value (i.e. 9 or 1) corresponding to the primitive succeecing 


or failing. The cxface. ned file defines TRUE and SVCCESS to be equal to 1, and FAIL anc 
FALSE to be equal to C. 
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Your C program will look something like this. (Note that this must be the first function definition in 
your source file, because after the code is loaded, execution Starts at the "top" of the code, which 
will be the first function defined in the file.) 


pool mycprim(argc, link) 
int argc; 
void (*link) (); 
variable declarations etc. 
set_link (link); 
if (arac != 2) 
return (FAIL); 


rest of program 


return (SUCCESS) ; 


r 


Tne argc parameter is the Prolog argument count. This particular program is expecting 2 Prolog 
arguments, and it immediately fails if this requirement is not met. The body of the program will 
probably make calls to the Prolog term access routines such as get_arg, get_tag etc., and to 
tne term construction functions to bind variabies. 


When the code is written, compile it The MPW command is 
 UsSercc 


Then link the resulting usez.c.o with xzace.o to produce the final code. 
For example, in MPW: 


link -rt MINE=10C user.c.o xface.o -o MyResource 


Tne -rt option declares the resource type to be MINE and the resource ID to be 100 (you may 
choose any resource type and ID). The resulting code resource will be in the file MyResource. 


The code mav then be run from MacPROLOG™ using the call_c primitive. Enter the clause: 


mycprim(A,B) :- 
call c(A,B, 'MINE', 100). 


After calling res_open to open the file tyResource, you can make calls to mycprim just as if 
it was an ordinary Prolog program. 


Note 

It is important that you specify user.c.o as the first file in the link sequence. If you do not, then 
the code's entry point will be somewhere other than you intended! 

Similarly, if you call other C functions, they must be defined in your source file after the main 
function which will be called from Prolog. 
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21.9.2 Using call_ic 


Suppose that you have a C code resource with resource type MINE and resource ID of 100, ina 


file called MyResource. In MacPROLOG, choose a name for the C primitive, say mycprin. 
Add a clause of the form: 


mycprim(A;, Aj, -«-+, Ap)in- 
call_c(Ajz, Ap, «++, Ap, ‘MINE', LOW): « 


If your C code handles different numbers of arguments, add such a clause for each arity. For 
example, if your C routine has a 2 argument form and a 3 argument form, you would add the 
following clauses: 


mycprim(A,B):- 1, 

call _c{A,B, 'MINE',100). 
mycprim(A,B,C):- 

call c(A,B,C, 'MINE',100). 


Before calling mycpr im, open the resource file containing the code: 
res open('MyResource'). 


Then you can call mycprim just as if it was an ordinary Prolog program. 


21.10 Technical Tips 
21.10.1 Memory Usage and Global Variables 


Since your code is written as a separate resource, you cannot use global (such as szaric) variables. 
You may only use local variables. If vou do try to use global variables, you may not get any 
compiler errors or warnings, but when you run the code you will be unwittingly overwnung the 
MacPROLOG™ application globals. This is not a good idea! 

If you need to use global variables, we suggest that vou allocate a block of memory in vour C code 
(using the Mac Memory Management routines), and pass the memory’s handle as a parameter o: 
the primitive. You could use the property handling primitives of MacPROLOG™ to store the 
handle. 


For example. in Prolog, your definition of '<LOAD>' might include the following 


res cpen('MyResource'), &ccen resource file 


set crop(myprim,memhandle,9), %initialise memhandle procerty 


When you first call the external primitive you pass the handle NIL. The C code can examine the 
handle, allocate memory if it is NIL, or otherwise simply use the memory indicated by the handle. 


Suppose mycprim would normally take two arguments. Your C code could look for third and 


fourth arguments, the third being the memory handle. and the fourth a variable which the C code 
will instantiate to the (possibly changed) memory handle on returning to Prolog. 
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The program for calling the C primitive might be as follows. 


mycprim({A,B) :- 
get_prop (myprim,memhandle, Handle), 
call _c(A,B,Handle, Newhandie, Result, 'MINE',100), 
set_prop(myprim,remhandle,Newhandle), 
Result is 1. 


This method allows for the handle to charge during execution of the C primitive (perhaps the 
memory block needs to grow, or be freed). However, because we always need to record the new 
handle, we cannot let the call to call_c fail. This means that the C code must always retum 
SUCCESS. However, the success or failure of mycpzim can be effected by adding another 
argument, Result, which can be bound to either 0 or 1 by the C code to indicate the failure or 
SUCCESS. | 

(The only other way that ca12_c can fail is if for some reason the code resource cannot be loaded. 
In this case Handle will not be used anyway.) 


21.10.2 Writing more than one C Primitive 


Each code resource has only one entry poin:. and therefore only one C function can be called from 
any given code resource. If you want to have more than one C primitive, one way to do it 1s to have 
several resource files, each containing a singie C program. However, this is not ideal, and a neater 
way of writing several C primitives is to use one of the following methods. 


Mi ethod ) 
You can combine several code resources into one file. 


Suppose you have files user .c, user2.z and usez2.c which each contain a C primiuve. 
After compiling each of the files, the following MPW commands will combine these into a single 
file. 


link -rt CCCA=0 user.c.o xlace.o ~o MyResource 
link -rt CCCB=0 userl.c.c xrace.o -o MyResource 
link -rt CCCC=0 user2.c.c xface.o -0 MyResource 


The file My=esource will contain three separate code resources of types CCCA, CCCP and CCCC 
respectively. 


Suppose these have arities of 1, 2 and 3, then the Prolog calls would be as follows: 


NYVpres tA) 

call _c(A, 'CCCA',2). 
myprim2 (A,B) :- 

call c(A, B, ‘CCz=',0). 
myprim3 (A,B,C) :- 

call c{A, B, C, "cccc',Q). 


NOTE In MPW you cannot link more than one code resource of the same resource type into one 
file. The MPW Linker deletes any code resources matching the given type before creating the new 
one, even if they have different resource ID's. This is why in the above example we have used the 
types CCCA, CCCB and CCCC rather than using one type and three different ID's. 
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Method 2 


You can create the effect of different primitives within a single code resource by passing a ‘selector 
flag from Prolog through to a single C function, and branching in the C code depending on the 
value of this flag. Such a C primitive might look something like this: 


bool myprim(argc, link) 
short argc; 
void (*link) (); 
{ 
set link (link); 
Switch (get int val(get_arg(1l))) 


{ 
case 1: 
return (prim: (argc) ); 
case 2: 
return (prim? (argc) ); 
etc. 
} 


} 


bool priml (argc) 
short argc; 
{ 
if (arge != 3) 
return (FAIL) ; 
sine ELC: 
} 


bool primd (argc) 
short argc; 
{ 
if (arge != 2) 
return (FAIL) ; 
etc. 


The corresponding calls from Prolog would be: 


MyCri Mlk) = 
call _c(1,X,Y¥, 'MINE',1CC). 
myprim2 (X):- 
ealloc(2, xX; "Miss ',100).. 
SCC: 


21.10.3 Storing Code Resources in Prolog Files 


A Prolog program (source or object code) is stored in the data fork of a file. This means that you 
can add resources (in particular, code resources) to 11 without affecting the Prolog code. It may be 
convenient to store your C code resources in the same file as the Prolog program that calls them. To 
do this, simply give the Prolog file name as the output file name when linking. 
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21.11 C Primitive Example 
The example given below demonstrates how to use some of the interface functions in writing a C 
primitive. The primitive is not a very useful one (in fact the same effect can be achieved using 
existing Prolog primitives), but it serves to demonstrate how to manipulate Prolog terms in C. 
Our primitive will take three arguments. The first may be either a constant, a list or a tuple 
(remember that a tuple is the MacPROLOG internal representation of a functor term). The second 
and third arsuments must be variables. 
The second argument will be bound to the length of the first argument. 
If the first argument is a constant, the third argument will become the text of the constant reversed. 
Otherwise a list will be converted to a tupie, and vice versa. 
The name of our new primitive in Prolog will be ctest. 
The call 

ctest (apples, X, Y} 
will bind ¥ to 6, and Y to the atom selrpé. 
The call 

ctest ([apples,pears,bananas], X, Y) 
will bind ¥ to 3, and Y to the term apples (pears, bananas). 
The call 

Ctest (£60.01 ,.252) > xy 1) 


will bind ¥ to 4, and Y to the lst [foo, 1, 2, 3}. 


196 


21 :C Interface 


21.11.1 C Source Code 
This is the source of the new C primitive. 


/* user.c 
* Sample C Primitive for LPA MacPROLCG™ 
*/ 


include "cxface.hed" /* Interface declarations */ 
bool test (argc, link) 

short argc; 

void (*link) (); 

{ 

cellpo: t1,t2,t2; 

int i, len; 

char stri[255],str2[255]; 


set link (link); /* "glue" us to MacPRCLOG */ 
if (argc != 3) 
return (FAIL); /* Check arz; count */ 
tl = get_arg(1); /* Read Prolca arguments */ 
t2 = get_arg(2); 
t3 = get_arg(3); 
if ((get_tag(t2) != VARTAG) || (get_tag(t3) ‘= VARTAG) ) 
return (FAIL); j® Fail if noz voles: */ 
switch (get_tag(tl)} is Look- -ar oroe of 1st arge T: 
{ 
case CONTAG: 
case STRTAG: 
len = get_con_len(tl); pe Ger ers. */ 
t2 = put _int Cart} lern); /* Bind 222 arg. to length */ 
get_con_text (strl, £1): fe Get text Ti 
for (i=0; i<ien; i++) ‘= Reverse giring */ 
str2 [i] = szriflen-1--]; 
str2[len] = °°.0'; = Terminata string * 
t3 = put. con: ~ext (t3, Str2); Bong, seas. 87 
return (SUCCESS) ; _* Return it Froloc * 


case LISTTAG: 


len = get_lisz_len(tl); ae See lensin t 

put int _val(t2,len); /* Bind 222 ara. to length */ 
put _tpl(t3,ien : Te “Make: Ses Seg A Cup ue */ 
for (i=l; i<=len; i++) /* Put list eis.into tuple */ 


{ 
put _copy_ceil(get_tpi_ nth(i,te).,det:..126=. zeaditlj) 
ti = get list_tail(t:); ‘x Walk through list * 
} 
return (SUCCESS); 
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case TPLTAG: 


len = get _tpl_len(ti); /* Get length */ 

put _int_val(t2,len); /* Bind 2nd arg. to length */ 
for (i=l; i<=len; i++) 

{ 


/* Create list x / 
puc fst (Cs), 


put copy cell(get_list_head(t3),get_tpl_nth(i,tl)); 
t3 = géet list tail(t3); 


put_nil(t3); /* Terminate list */ 
return (SUCCESS); 

default: 
return (FAIL); 


/* Fail if not correct type */ 


Note the methods used for creating and readirg lists and tuples. In particular, to create the list 
above, we 


i) construct a LISTTAG cell: 
put 225-2 os) 

ii) bind its head term to a copy of the ith tupie cell: 
put. coo, cell tae] 235. De 


22'23),get_cpl nth(i,tl)),; 
iii) and get a pointer to the tail cell 


o = Get list casi (ts); 


This will then be bound to another LISTT2@ cell at the top of the next loop, and so on. 


iv) To terminate the list we must make the final 'tail' a NILTAG cell: 
put natal 


/* Terminate list */ 
21.11.2 Compiling, Linking and Running 


When this source text has been entered, it may be compiled and linked with the MPW commands 
C usez.c 


link -rt TEST=C user.c.o xiece.o Testfile 
Now Test file contains the code resource ready for calling from MacPROLOG. 
In Prolog, enter the following definition of ctest: 


ctest (X, Y, Z):- 


call_c(X, Y, Z, "EST"; Oy). 


After opening the resource file: 
res open('Testfile') 


ctest may be called and will exhibit the behaviour described above. 
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21.12 Technical Specification and Calling Conventions 


The C interface files and functions have been written according to the following conventions. 


21.12.1 Data Types 


A short int occupies 16 bits. 

An int occupies 32 bits. 

A floating point number of type extended occupies 80 bits. 
Strings are terminated with a null character ('\0'). 


21.12.2 Interface Functions Calling Conventions 


All the interface functions (such as get_int val.cut_real_-7ai etc.) are declared to be 
‘pascal’ type functions, which means they conform to the following calling conventions (this 
corresponds to the conventions used by the Macintosh Toolbox routines). 


Parameters are evaluated from left to right, and are pusned onto the stack in that order. Space for 
the function result is reserved on the stack by the caller before pushing any parameters. The calles 
is responsible for removing the parameters. 


A short int 1s passed as a 16 bit value. 

An int is passed as a 32 bit value. 

An extenced number is passed as a 32 bit pointer to an 80 bit value. When an extence=: 
number is to be returned as a function result (e.g. in s2=_ real val), the caller must allocice 
space for the 80 bit value and push a 32 bit pointer to iis buffer in the place of the function resvi: 
(i.e. this pointer is pushed on the stack before the other parameters to tne function call). 

A string pointer is passed as a 32 bit value. 


21.12.33 C Calling Conventions 


A C function's parameters are evaluated from night to ier: and are pushed on the Stack in that order. 


The caller is responsible for removing the parameters from the stacx. Parameters are pushec ¿s 
described above except that a short int is sign extended and pusnec as a 32 bit value. 


The function result is returned in registers rather than on the stack. In particular, the boolean resu.: 
of a C primitive is expected in the low byte of register DO. 


199 


21 : C Interface 


21.12.4 Examples 


1, When the Prolog call_c primitive calls a C pnmitve, the following operations are performed. 
Recall that the C function has the form 


bool cpvrim(argc, Link) 
short argc; 
Vorc {LIREI I; 


1) Push the Link parameter on to the stack as a 32 bit value 

t) Push the Prolog argument count as a 32 bit value, sign extended from a 16 bit value 

w) Call the C code 

iv) Clear from the stack the two 32 bit parameters to the C call 

iv) Read the C function result in the low byte of DO. If itis zero, fail the Prolog call, otherwise 
succeed tne call. 


2. Consider the put_int_v=L function, which is declared as 
pasce- Celipe Te- 20t veo vos, val) 
Ge oes: cp; 


bY LD 


~ 


pig pi 


The code for this function is written in assembiy language and does the following operations. 


i) Pop tne retum address from the stack 

ii) Pop the val parameter as a 32 bit vaiue 

ii) Pop the cp parameter as a 32 bit value 

iv) Push the return adaress 

v) Create the Prolog term, bind it to the cell at cp etc. 

vi) Move the 32 bit celico result to just above the return address (i.e. to Stack Pointer + 4) 
vii) Return to C 
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22.1 Introduction 


MacPROLOG™ allows you to write your own primitives in Pascal and call them directly from 
within Prolog. The primitives must be compiled as separate code resources, and they are then 
loaded as they are needed by the Macintosh Resource Manager. This means that there is no need to 
rebuild the LPA MacPROLOG™ application file, but you can create your Own separate library o: 
Pascal routines which are callable from Prolog. The extent to which these new primitives behave 
like a program written in pure Prolog depends on how many of the primitive'’s uses have beer. 
catered for by the Pascal programmer. 


A Pascal primitive may have arguments passed to it from Prolog. Trere is a collection of interfcz2 


routines which allow you to access these arguments and their values, and return vaizes to Prois? 
by binding the variables of the call. 


Like a Prolog program, a Pascal primitive either succ22cs or fails, possibly binding variables ine 
srocess. Unlike a Prolog program, however, the Pasca primitive cannot be non-Geteministic: i262: 
is, you cannot backtrack into it to evaluate alterna::ve solutions. If vou want this benaviour, Cz 
can write a Prolog program to sequence through non-deterministic solutions to your Pasca: 
primitive. 


Having wnuen your new primitive as a code resource. it is called from within Prolog with :n2 
call pascal pnmitive, which will load and run the specified coce. Prolog arguments to ie’ ce. 
may be accessed from within the Pascal code. 


22.1.1 Requirements 


To use the Pascal Interface, you will need the supz.ied library of Prolog interface functions. 4 
Pascal Compiler and Linker, and a 68000 Assembler. 


Important Note 

LPA MacPROLOG™ was written using the MPW ‘M{acintosh Programmers’ Workshop) packaze. 
and instructions for creating code resources here reler to MPW. If vou use a different compie. 
there may be differences in function calling conventions, and you may have to Make sori 
adjustments to the supplied source files or to the way in which you call the Prolog interace 


functions. See the Technical Specification Section for further detaus. 
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22.2 Calling a Pascal Function - An Outline 


Here we sketch the format of a Pascal primitive and the method of calling it from Prolog. For a 
more detailed description, refer to later sections of this chapter. In particular, a complete example is 
given at the end of this chapter. 


When a Pascal program is called from Prolog it will be called with two arguments. 


The first argument (argc in the example below) is an integer giving the number of Prolog 
arguments to the call. (You can read these Prolog arguments using the get_arg function, 
described later in the Term Access Functions section.) 


The second argument is a pointer to a routine in the MacPROLOG™ application code which the 
various Prolog term access routines use. This second argument must be passed on to the 
set link procedure (defined in the interface files) as the first call of your Pascal code; thereafter 
this Link argument may be ignored. The sez_ link procedure does the "gluing" of your code 
resource to MacPROLOG™,. 


The Pascal primitive must return a Boolean value corresponding to the primitive succeeding or 
failing. The interface file defines SUCCESS to be equal to TRUE, and FAIL to be equal to FALSE. 


Your Pascal program will look something like this. 


onction Myprim (argo :integer:it isk: 1onginr)t boolean; 
variable declarations etc. 


BEGIN 
set lank (link); 
if argc <> 3 then 
myprim := FAIL; 


rest of program 
mycrim := SUCCESS; 
END; 


As described above, argc is the Prolog argument count. This particular program is expecting 3 
Prolog arguments, and it immediately fails if this requirement is not met. The body of the program 
will make calls to the Prolog term access routines to read the three Prolog arguments, and to the 
term construction functions which will bind any vanables of the call. 


The Pascal code must then be compiled and linked as a code resource (you may give it any resource 
type and ID). It is then called from MacPROLOG using the call_ pascal primitive (see below). 
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22.3 call pascal - load and run a Pascal code primitive. 


call pascal(A,z,Ap,..-,Ay, restype, resid) 


ARGUMENTS 
Az Ad, Ap : Prolog arguments to the Pascal primitive 
restype 7 resource type of code resource 
resid - resource ID of code resource 


This call loads and runs a Pascal routine in the code resource identified by the rest ype and 
residarguments. The first k arguments to call_cascal willbe placed in the Prolog argument 
registers for subsequent access by the Pascal primitive. 


Note that the resource file containing the resource will nor be automatically opened oy 


The call_pascal primitive will succeed or fail depending on the SUCCESS / FAIL result 
passed back from the Pascal primitive. call_pascai will also fail if the resource cannot oe 
loaded for any reason. This would happen if, for example, the resource file was not open. 


EXAMPLE 


Suppose you have a Pascal program in a code resource of type INE and with ID 100, whieh 
expects 3 arguments. If in Prolog you name this primitive pasczrim, then you would ade tne 
following clause. 


() 
th 


cascprim(sa,2,C):- 
call _pascal(A,B,C, 'MINE',i¢%). 


After you have opened the resource file containing your code resource (by calling res oer. 
pascprin can be called just like any other Prolog program. 
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22.4 Storage of Terms in MacPROLOG 


In order to make use of the functions providing an interface to Prolog, you need to be aware of 
how MacPROLOG stores terms internally. You do not need to know exact memory layouts but you 
need to know about the various term structures and how they are represented. The following 
discussion in this section describes the general storage mechanism for Prolog terms; the next 
section gives details about individual data rypes. 


22.4.1 Tagged Cells 


A term in MacPROLOG is stored in a tagged cell. The tag of the cell indicates the type of data 
stored in the cell, and the rest of the cell represents its value. 


Access to these cells from Pascal is always via cell pointers. The type cellpo is defined in the 
Pascal interface to be a tagged cell pointer. 


All term manipulation 1s done by passing cell pointers to the various term access and construction 
functions provided. You will never manipulate the tagged cells directly. 


The Pascal interface provides a number of these term access functions which allow a Pascal 
program to find out about the term stored in a particular cell. For example, the gez_ int vai 
function returns the integer value of an integer cell. There are also a number of term construction 
functions which allow new Prolog terms to be built and returned as bindings for existing unbound 
variables. For example, the put _ list function binds a variable to a Prolog list structure. These 
functions are described in more detail later. 


These term access and construction functions present a fairly abstract view of the MacPROLOG 
data structures, and therefore you need not be over concerned with the exact internal representation 
and memory layout of Prolog terms. 


22.4.2 Prolog Argument Registers 


A Pascal function can access the Prolog arguments given in the call to call pascal. There are 
31 Prolog argument registers each of which can hold any Prolog term (i.e. a tagged cell). There 
may therefore be up to 31 Prolog arguments to the Pascal function which will be placed in these 
argument registers. The interface function get _arg can then be used from within Pascal to read 
these arguments. get_ arc will retum 2 pointer to the term cell in a specified Prolog argument 
register (see the Term Access Functions section below). 
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22.5 MacPROLOG Term Structures 


There are seven different term types in LPA MacPROLOG™. These are detailed below. As 
described above, each Prolog term is held in a tagged cell. The tag values (defined in the interface 
files) are as follows. 


TERM TYPE TAG 
Variable VARTAG 
Integer INTTAG 
Real REALTAG 
Constant CONTAG or STRTAG 
List LISTTAG 
Empty List NILTAG 
Tuple TPLTAG 
22.5.1 Variable 


A VARTAG cell represents an unbound variable. Such cells may be bound to other Prolog terms 
using the term construction primitives such as put_int_val, put_con_text ete. 


22.5.2 Integer 


An INTTAG cell represents an integer, stored as a 24 bit signed value. Note that Pascal uses 32 bits 
for integers, but integers outside the range -8388608 to 8388607 will not be correctly represented 
in Prolog. 


22.5.3 Real 


A REALT3G cell represents a floating point number. It is stored as an 80 bit value, which 
corresponds to the Pascal data type extended. 

(Note that in MacPROLOG™ real numbers are automatically converted to integers if possible, so 
that when you construct a real cell you may sometimes get an integer cell instead). 


22.5.4 Constant 


A CONTAG or STRTAG cell represents some text stored as a sequence of ASCI characters. The cell 
may have either of the two tags CONTAS OF STRTAG, which merely reflects whether the text 1s 
stored as a permanent’ dictionary entry or as a ‘temporary’ object in the Prolog ‘heap. The actual 
format of the stored text is identical in each case. 
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22.5.5 List 


A LISTTAG cell represents a Prolog list structure. The list cell actually points to two more term 
cells, one representing the term at the head of the list, and the other representing the tail. The tail 
will usually be another LISTTAG cell, or the empty list (i.e. a NILTAG cell). 
For example, the Prolog list 

(10; Cat, 239] 
is represented by a LISTTAG cell which points to an integer cell with the value 10, and another 


LISTTAG cell. This second list cell points to a constant cell with the value cat, and a third list 
cell, which in turn points to a real cell with value 2.5, and a NILTAG cell. 


Herme 








Thus the internal representation of the above list is 


(10, [cat, [2+5 []] ] 1 


22.5.6 Empty List 


ANILTAG cell represents the empty list. As described above, one of its uses is as a ‘tail cell to 
terminate a list. A NILTAG cell has no "value". 
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22.5.7 Tuple 


A TPLTAG cell represents a Prolog tuple structure. A tuple is a fixed size array of elements, where 
each element is any Prolog term. This corresponds to the internal representation of a functor and its 
arguments. 


For example, the Prolog term 

£606 (10.70;.30) 
is represented internally as a tuple with four elements, the first element being a constant cell with 
value foc, and the remaining elements being integer cells with values 19, 20 and 27. 
(MacPROLOG also stores an extra “size” cell at the beginning of the tuple structure which gives the 
number of tuple elements.) 


The above tuple therefore looks like this. 





Since a tuple is a fixed size, it has a more compact representation than a ist. 
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22.6 Pascal Interface Term Access Functions 


These functions allow you to read Prolog terms from within Pascal. As mentioned above, a Prolos 
term is stored in a tagged cell, but all term manipulation is done using pointers to these cells. 


All these functions are declared in the file sxface.hed (which you will include in your Pascal 
source file). 


Note that these functions will do no checkins of arguments: you are responsible for ensuring that 
any arguments you pass to one of these routines are of the correct type. For example, if you pass a 
LISTTAG cell pointer to the function get_con_text, there is no guarantee of what the results 
might be! 


The types celipo (a tagged cell pointer}. cxt (a 255 character string) and txtpo (a string 
pointer) are declared in the file pxface.nec. 


This function returns a pointer to the cell in Prolog argument register num, where num ranges from 
l] to argc (tne Prolog argument count, passed as a parameter to your Pascal function). You may 
read the Prolog argument registers in any orcer. However, there is no guarantee that you will ce: 
anything sensible if you try to read 2 register beyond argc. (There are no checks done by 
get_arg on the validity of num.) 


22.6.2 get tag 


This function retums the tag of a Prolog cell pointed to by xv. The value returned will be one of: 
VARTZ2 INTTAG REALTAG CONTA? STRTAS LISTTAG NILTAG TPLTAS 


The tag indicates the type of the data stored in the cell. 


22.6.3 get_int vai 
function get_int_val(cs:cellpo) :iongint; 
This function returns the integer value of an -NTTAG cell pointed to by cp. As described above, 


although a Pascal longint type is retumec, only the lower 24 bits are used by MacPROLOG. 
(The integer returned by this function will have been sign extended to 32 bits). 
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22.6.4 get_real_val 


function get_real_val(cp:cellpo) :extended; 


This function returns the real (floating point) value of a REALTAG cell pointed to by cp. 


22.65 get _con_text 
function get_con text (str:txtpo;cp:cellpo) :txtpo, 
This function returns the text of either a CCNTAG or STRTAG cell pointed to by cp. The text will 


be copied as a Pascal string into the buffer pointed to by str; this pointer is also returned as tne 
function result. 


You must ensure that str points to a string buffer large enough to hold the text: tie 
zet con_text function does not allocate any space for you. 


22.6.6 get _con_len 
function get_con_len(cp:celiso):longint; 


This function returns the actual number of characters in the text of the CONTZG or STRTAG ceil 
pointed to by cp. 


If cp points toa LISTTAG cell, this function returns a pointer to the cell representing the term « 
the head of the list. 


22.6.8 get _list_tail 


function get _list_taili(cp:celipo):celipo; 


If cp points to a LISTTAG cell, this function returns a pointer to the cell representing the tail of tne 
list. 
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22.6.9 get _list_len 
function get list _len(cp:cellpo):longint; 


If cp points to a LISTTAS cell, this function returns the length of the list (i.e. the number of 
elements in the list). 


22.6.10 get _tpl_len 
function get_tpl len(cp:cellpo) :longint; 


If cp points to a TPLTAG cel, this function returns the number of elements in the tuple. 


22.6.11 get_tpl_oneb 


Fa, 


onction gsn 2 ol Men (os ono: 7p: cet) celle, 


If cp points to a TPLTA® cell, this function returns a pointer to the cell representing the nu: 


element of the tuple. The first element of the tuple is numbered 1. The value of ntz should no: 
exceed the length of the tun:e. 
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22.7 Pascal Interface Term Construction Functions 

The following functions allow you to construct new Prolog terms and to bind existing unbound 
variables to them. Each function expects to be passed a pointer to an unbound variable (i.e. a 
pointer to a VARTAG cell), which will then be instantiated to a new Prolog term. The function 
returns a pointer to this newly created term. 


In a simialy way to the term access routines, no check is made that the cell pointer does in fact point 
to a VARTAG cell. 


These bindings will automatically be undone on backtracking. 
You should not try to construct a new term in a cell which is not a variable, as this is not logical and 


may lead to strange results. 


22.7.1 put_int_val 


function put_int_val(unb:ceilss;val:iengiat) :cellpo; 


This function constructs an integer cell and binds it to the variable pointed to by unb. As mentioned 
previously, only the lower 24 bits of val are stored. 


22.7.2 put _real_val 
function put _real_val(unb:ceiisc;val:extended) :cellpo; 
This function constructs a real cell and binds it to the variable pointed to by unb. As notec 


previously, if val can be expressed as an integer, an integer cell wijl be constructed instead. Thus 
the tag of the constructed cell may be either REALTAS or INTTAS. 


22.7.3 put_con_text 

fonction put_con text (unb:celiro;str:cxcso) :cellpo; 
This function constructs a constant cell from the string pointed to by str and binds it to the 
variable cell pointed to by unb. The tag of the returned cell will be either CONTAG or STRTAG. 
22.7.4 put_list 

function put_list(unb:cellpo) :ceilpo; 
This function constructs a list cell and binds it to the variable pointed to by unb. Two extra cells are 
created, one for the head of the list and one for the tail. Both of these will be initialised to unbound 


variables. You can access these cells (and bind new Prolog terms to them) using the 
get_list_headand get_list_tail functions. 
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22.7.5 put_nil 
function put_nil(unb:cellpo) :cellpo; 


This function constructs an empty list cell (a NILTAG cell) and binds it to the variable pointed to by 
unb. 


22.7.6 put _tpl 
function put tpl (unb:cellpo;size:longint) :cellpo; 


This function constructs a tuple cell and binds it to the variable pointed to by unb. An array of extra 
cells is created for the size tuple elements. Ali of these will be initialised to unbound variables. 


You can access these cells (and bind new Prolog terms to them) using the get_tpl_ntn 
function. = 


22.7.7 put _copy_cell 


Turen ron put _copy_cell (sest, srce:cellpo) :cellpo; 


This function copies the term pointed to by sxc to the term pointed to by dest. The functor 
returns a pointer to the dest term. 

The destination cell must be an unbound variable at the time of the call, but the source cell may De 
any Prolog term (including another unbound variable). If you use this function to copy one variadi 
cell to another, the effect is to make both cells refer to the same variable, and binding one of these 
variables to 2 new Prolog term automatically binds the other vanable to the same term. 


22.8 Reporting Errors from a Pascal Primitive 


If you wish to report an error from within your Pascal code, you may call the procedure 
errortras with an error code signalling the type of the error. 


22.8.1 ezrortrap 

procedure errortrap(errno:integer); 
This procedure generates a Prolog numbered error. It does not retum control to the calling rouune, 
but jumps straight to the Prolog error handler. The error will be handled in exactly the same way as 


any other Prolog error. See the chapter on Implementing an Application for more details on error 
handling, and the Appendix for details of the error numbers available. 
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22.9 Creating a Pascal Primitive 


NOTE This documentation assumes you are using the Macintosh MPW Pascal Compiler, 68000 
Assembler, and Linker. If you are using a different Compiler and Linker you may need to refer to 
your own manuals for specific instructions on creating code resources. 

See the Technical Specification section to determine what changes, if any, you may need to make to 
the Pascal or Assembly language source code provided with MacPROLOG. 


To create a new Pascal primitive for MacPROLOG you will need the files xface.c, 
pxface.hed and user.p. 


xface.o is an object code file containing the routines giving access to the Prolog data structures. 
It is written in assembly language, and needs to be linked in with your Pascal object code to create 
the final code resource. 

NOTE The source for xface.o is in the file xface.a, which you will only need to use if you 
find that the format of xface.o is not compatible with your Linker. In this case, you will neec : 
assemble xface.a using an appropriate 68000 Assembler, (first making any textual changes to 
the source to conform to your assembler's syntax and other features) before linking the resulting 
object code with your Pascal object code file. : 


pxface.hed is a text file to be included in your Pascal source code file, user . p. It contains 
all the type and function declarations needed to interface with Prolog. 


user.p is a text file which will contain the source for your Pascal primitive. 


22.9.1 The Format of a Pascal Primitive 
When a Pascal program is called from Prolog it will be called with two arguments. 


The first argument is an integer giving the number of Prolog arguments to the call. (You can rez 
these Prolog arguments using the get_arg function, described in the Term Access Funct:cns 
section.) 

The second argument is a pointer to a routine in the MacPROLOG™ application code which tne 
various Prolog term access routines use. Ail you need to do with this second argument iS pass i: on 
to the set_ link procedure as the first procedure call of your Pascal code; thereafter you shouid 
ignore this “link” argument. The set_link function does the “gluing” of your code to 
MacPROLOG™; if you omit to call set_link you can expect to nave serious errors! 


The Pascal primitive must return a boolean value corresponding to the primitive succeeding or 


failing. The pxface .hed file defines SUCCESS to be equal to 7=UE, and FAIL to be equa: to 
FALSE. 
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Your Pascal program will look like this. (Note that this must be the firsr function definition in your 
source file, because after the code is loaded, execution starts at the “top” of the code, which will be 
the first function defined in the file.) 


function myprim(argc:integer;link:longint) :bool; 
... variable declarations etc. 


BEGIN 

set link (link); 
if argc <> 2 then 
myprim := FAIL; 


.. rest of program 
myprim := SUCCESS; 
END; 


Note that arac is the Prolog argument count. This particular program is expecting 2 Prolos 
arguments, and it immediately fails if this requirement is not met. The body of the program wii. 
probably make calls to the Prolog term access routines such aS get_arg, get_téz etc., and te 
the term construction funcuons to bind variables. 


When you have written the code, compile it. In MPW, the command is 


t1 


ascal user. 


Then link the resulting user .p.o with xface.o to produce the final code. 
For example, in MPW: 


Tink -rt MINE=100 usez.c.o xfaece.o -0 MyRKesource 


The -rt option declares the resource type to be MINE and the resource ID to be 1¢ 2° (you may 
choose any resource type and ID). The resulting code resource will be in the file MyResource. 


The code may then be run from MacPROLOG™, after calling res_open to open the file 
MyResource, using the cai ]_pasca primitive: 


myprim(A,B,C}:- 
call pascal (A,B,C, 'MIN=',100). 


NOTE 
It is important that you specify user . p . o as the first file in the link sequence. If you do not, then 


the code's entry point will be somewhere other than you intended! 
Likewise, the Pascal primitive has to be the first function definition in the source file user . p.. 
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21.8.1 Using call_pascal 


Suppose that you have a Pascal code resource with resource type MINE and resource ID of 100, in 
a file called MyResource. In MacPROLOG, choose a name for the Pascal primitive, sav 
myprim Add a clause of the form: 


myprim(A;, Aor coy Ay) r= 
call pascal (Aq, Ad, on oF Ags INE?’ f 100) a 


If your Pascal code handles different numbers of arguments, add such a clause for each arity. For 
example, if your Pascal routine has a 2 argument form and a 3 argument form, you would add the. 
following clauses: ’ 


myprim(A,B) :- 

call pascal (A,B, 'MINZ', 100). 
myprim(A,B,C):- 

call pascal (A,B,C, 'MIvNeE',100). 


Before calling myprim, open the resource file containing the code: 
res open('MyResource'). 


Then you can call myprim just as if it was an ordinary Prolog program. 


22.10 Technical Tips 
22.9.1 Memory Usage and Global Variables 


Since your code is written as a separate resource, you cannot use giobal variables. You may or.» 
use local variables. If you do try to use global variadles, you may not get any compiler errors c: 
warnings, but when you run the code you will be unwittingly overwriting the MzcPROLOG™ 
application globals. This is not a good idea! 

If you need to use globai variables, we suggest that vou allocate a block of memory in your Pesce. 
code (using the Mac Memory Management routines.. and pass the memory’s handle as a parameter 
of the primitive. You could use the property hanci:ng primitives of MacPROLOG™ to store :n2 
handle. 


For example, in Prolog, your definition of '<LOAD>' might inciuce the following 


res open('MyResource'), 
sez prop (myprim,memnandle,0), 


When you first call the Pascal primitive you pass the handle NIL. The Pascal code can examine the 
handle, allocate memory if it is NIL, or otherwise simpiv use the memory indicated by the handle. 
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Suppose myprim would normally take two arguments. Your Pascal code could look for third and 
fourth arguments, the third of which is the memory handle, and the fourth a variable which the 
Pascal code will instantiate to the (possibly changed) memory handle on returning to Prolog. 


The program for calling the Pascal primitive might be as follows. 


myprim(A,;5) += 
get_prop(myprim, memnandle, Handle), 
call pascal(A,B,Handle,Newhandle, Result, 'MINE', 100), 
set prop (myprim, mernandle,Newhandle), 
Result is i. 


This method allows for the handle to change during execution of the Pascal primitive (perhaps the 
memory block needs to grow, or be freed). However, because we always need to record the new 
handle, we cannot let the call to call _pascai fail. This means that the Pascal code must always 
return SUCCESS. However, the success or failure of mycrim can be achieved by adding another 
argument, Result, which can be bound to either 0 or 1 by the Pascal code. 


(The only other way that call pascai can fail is if for some reason the code resource cannot be 
loaded. In this case Handie will not be used anyway.) 


22.9.2 Writing more than one Pascal Primitive 


Each code resource has only one entry point and therefore only one function can be called for any 
given code resource. If you want to write several Pascal primitives you could have several flies 
each containing a single code resource. However, a neater way of handling several Pascz: 
primitives is to use one of the methods below. 


Method ] 
You can combine several code resources into one file. 


Suppose you have files user.p,user2.p and user3.p each of which contains a Pasce; 
primitive. After compiling each of the files, in MPW you could issue the following commands to 
combine these into a single file. 


link -rt PASA=0 user.p.c xface.o -o MyResource 
link -rt PASB=0 userl.p.c xface.o -o MyResource 
link -rt PASC=0 user2.p.o xface.o -o MyResource 


The file MyResource will contain three separate code resources of types PASA, PASB and PAST 
respectively. 


Suppose these have arities of 1, 2 and 3, then the Prolog calls would be as follows: 


mypriml (A) :- 

call pascal (A, 'PASA',0). 
myprim2 (A,B) :- 

call pascal(A, B, "PASB',0O). 
myprim3 (A,B,C) :- 

call _pascal(A, B, C, 'PASC',0). 


Note In MPW you cannot link more than one code resource of the same type into one file. The 
MPW Linker deletes any code resources matching the given type before creating the new one, even 
if they have different resource ID's. This is why in the above example we have used the types 
PASA, PASB and PASC rather than using one type and three different ID's. 
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Method 2 


You can create the effect of different primitives within a single code resource by passing a ‘selector 
flag from Prolog through to a single Pascal function, and branching in the Pascal code depending 
on the value of this flag. Such a Pascal primitive might look something like this: 


function myprim(argc:integer;link:longint) :boolean; 
BEGIN 
set, link (link); 
case (get_int_val(get_arg(1))) of 
1: 
myprim := primli (argc); 


myprim <= prim2 (argc); 
CEG. 


end; 
END; 


function priml(argc:integer) :booleas; 


BEGIN 
if argc <> 3 then 
priml := FAIL; 
etc. 
END; 


function prim2(argc:integer) :boolean; 


BEGIN 
if argc <> 2 then 
prim2 := FAIL; 
etc. 
END; 
ecc. 


If the resource is of type MINE with ID 199, the corresponding calls from Prolog would be: 


Mypsiml (A; sya 
call pascal (ly X; ty MINE”; 203) 4 
MOCI (X) = 
call pascai(2, X; "MINE"; 1L) 
etc. 


22.9.3 Storing Code Resources in Prolog Files 


The source or object code of a Prolog program is stored in the dara fork of a file. You can store 
your Pascal code resources in the resource fork of the same file if sou wish. You may find :: 
convenient to store Pascal code resources in the same file as the Prolog program that calls them. To 
do this, simply give the Prolog file name as the output file name when vou link the code resources. 
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21.11 Pascal Primitive Example 
The example given below demonstrates how to use some of the interface functions in writing a 
Pascal primitive. The primitive is not a very useful one (in fact the same effect can be achieved 
using existing Prolog primitives), but it serves to demonstrate how to manipulate Prolog terms in 
Pascal. 
Our primitive will take three arguments. The first may be either a constant, a list or a tuple 
(remember that a tuple is the MacPROLOG internal representation of a functor term). The second 
and third arguments must be variables. 
The second argument will be bound to the length of the first argument. 
If the first argument is a constant, the third argument will become the text of the constant reversed. 
Otherwise a list will be converted to a tuple, and vice versa. 
The name of our new primitive in Prolog will be pasctest. 
The call 

pasctest (app-es, X, Y) 
will bind X to 6, and Y to the atom selppé. 
The call 

pasctest ([apr_es,pears,bananas}, X, Y) 
will bind X to 3, and Y to the term apples (pears, bananas}. 
The call 

pasctest (fool.,2,3), X, Y) 


will bind X to 4, and Y to tre list {foo, 1, 2, 3). 
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22.10.1 Pascal Source Code 
This is the source of the new Pascal primitive. 


(* user.p 


x Sample Pascal primitive for MacF2OCLOG™ 
=) 


unit MyPascal; 

interface 

function test (argc:integer;link:lonzint) :booiean; 
implementation 

{SI pxface.hed} 


function test (argec:integer;link:lensint) :boolean; 


VAR 
tl¢t2,;ts;cemp: i. cell po; 
Len, 2. £ P6ngint; 
text, rtext : txt; 
CPO : txtpo; 
BEGIN 
set_link (link); 
if arac <> 3 then { Fail if not ł args 
test := FAIL; 
ti := get arg(1); { Read the args 
t2 := ger arg(2); 
t3 := ger arg(3); 
if (get tag (tz) <> VARTAG) I (gel -Sc(t3) <> JARIAG) ‘thes 
tesz := FAIL; (zoca 2) NOt voles 
case (cet tagitl)): of l neon, ae LSL 255. 


CONTAG, STRTAG: 


begin 
len := get_con_len(t1); ices Length. -j 
t2 := put_int_val(t2Z,ien); tL 2250 2G arg i 
tpo <= get con text: (etext, ti); { cet text } 
for i := 1 to len do { reverse string } 
rrext[i] := text([lentl-1]; 
rtext[0O} := char (ler); 1 222 Lengri an: 
t3 := put_con_text (t3, @rtext} ; { sind 3rd arg. } 
test := SUCCESS; t Frecurn. to Proog 
end; 
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LISTTAG: 
begin 
len := get_list_len(tl); { Get length.) 
t2 := put_int_val(t2,len); { Bind 2nd arg } 
t3 := put tpl(t3, len); { Make 3rd arg a tuple } 
for i:=] to len do { Copy list elts. in } 
begin 
temp:=put_copy cell(get_tpl nth(i,t3),get_list_head(tl)); 
ti a= Gece List CALLEN { Walk thro’ list } 
end; 
test := SUCCESS; 
end; 
TPLTAG: 
begin 
lenr := get tpl ten (tl); {Get t6ngch J 
t2 t= put int vąaltt2;łleni; { Bind 2nd arg } 
for i:=1 to ler ‘do { Create list ... } 
begin 
to = put J1sc(ts), 
temr:=put_copy_cell(get list head(t3),get_tpl_nth(:,tl)); 
to q= get lIs tail (ts); { Walk thro” list } 
enc; 
t3 f= put nilit3i { Terminate list } 
tes= := SUCCESS; 
enc; 
otherwise { Fail if arg not correct type } 
test := FAIL; 
end; { of CASE statement } 


END; { of test function } 


END. { of source } 
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Note the methods used for creating and reading lists and tuples. In particular, to create the list 
above, we 


1) construct a LISTTAG cell: 
t3 := put list (t3); 


ii) bind its head term to a copy of the ith tuple cell: 
temp:=put_copy cell(get_list_hesac(t3), ge z_tpl_nth(i,t1)); 


iii) and get a pointer to the tail cell 
Cs. ¿= get list tail(t3); 


This will then be bound to another LISTTAG cell at the top of the next loop, and so on. 


iv} To terminate the list we must make the final ‘tail’ a NILTAG cell: 
tS := put nil(t3); ( cerni nate List j 


22.10.2 Compiling, Linking and Running 
When this source text has been entered, it may be compiled and linked with the MPW commands: 


pascal user.p 
link -rt TEST=0 user.p.o xfacs.z Testt:- 


Now Testile contains the code resource ready for calling from MacPROLOG. 


eer et 


pasctest (X, Y, 2):- 
Gall pascal; Yy Zy “Seley. UJ 


After opening the resource file: 
res -open( "test lilte*) 


pasctesz may be called and will exhibit the behaviour described above. 
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22.11 Technical Specification and Calling Conventions 


The Pascal interface files and functions have been written according to the following conventions. 


22.11.1 Data Types 

An integer occupies 16 bits. 

A longint occupies 32 bits. 

A floating point number of type extended occupies 80 bits. 

Strings are stored as a sequence of ASCII codes each occupying one byte, with a length byte at the 
beginning. 

2?.11.2 Interface Functions Calling Conventions 


All the interface functions (such as ge=_ int _vai,sut_real_val etc.) conform to the 

following calling conventions. (This corresponds to the conventions used by the Macintosh 

Toolbox Toutings). 

Parameters are evaluated from left to righ:, and are pushed onto the stack in that order. Space for 

the function result is reserved on the Stack: bv the caller before pushing any parameters. The callee 

is responsible for removing the parameters. 

An integer is passed as a 16 bit value. 

å longinz 1s passed as a 32 bit value. 

An extended number is passed as a 32 bit pointer to an 80 bit value. When an extended 

dea is tc be returned as 2 function resuit (e.g. in qs real val), the caller must allocate 
e for the 80 bit value anc push a 32 bit pointer to this Duffer in the place of the function result 

(i. P ak pointer is pushed on the stack before the other parameters to the function call). 

A string pointer is passed as a 32 bit vaiue. 


A boolean result is returned in the high byte of a 16 bit word. 
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22.11.3 Examples 


i. When the Prolog call pascal primitive calls a Pascal primitive, the following operations are 
performed. Remember that the Pascal primitive will be defined as 


function prim(arge:integer;linx:longint) :poolean; 


i) Push a 16 bit value on the stack to reserve space for the function result 

ii) Push the Prolog argument count argc on to the stack as a 16 bit value 

iji) Push the link parameter as a 32 bit value 

iv) Call the Pascal code 

v) Pop the Pascal function result as a 16 bit value. If the high byte is zero, fail the Prolog call, 


otherwise succeed the call. 


2. Consider the put_int_val function, which is ceclared as 
-function put_int_val(ce:cellpc;val:longint) : cellpc; 


The code for this function is written in assembly language and does the following operations. 


1) Pop the retum address from the stack 

il) Pop the val parameter as a 32 bit value 

11) Pop the cp parameter as a 32 bit value 

iv) Push the return address 

y) Create the Prolog term, bind it to the cell at cr etc. 

vi) Move the 32 bit cel lpo result to just above the retum address (i.e. to Stack Pointer + 4) 


vil) Return to Pascal 
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23.1 Introduction 


Welcome to the MacPROLOG Graphics package. This package combines the Macintosh's 
sophisticated graphics with the programming power of MacPROLOG in a high level and 
declarative fashion. Graphic pictures, which can originate from inside MacPROLOG or be 
imported from external applications (MacDraw, MacPaint etc.), can be displayed both in dialogues 
and in a special type of window, the graphic window. 


Pictures created within MacPROLOG are defined as terms of a Graphic Description Language (the 
GDL). This declarative language uses a natural, economic but powerful notation in which 
structured pictures are described as combinations and modifications of elementary pictures. 


For example 


crosses ([thick (fillbox (0,0,30,40)), l 
greypen (pensize(2,z,£illoval (20,0, 60,60)))]) 


describes a structured picture comprising an overlapping box and oval, both filled with a crossec 
patrem, with the box having a thick black outline, and the oval a thinner grey outline. 

The fillbox and filloval are elementary picture descriptors; and pensize, thick, anc 
greypen are picture transformers. 


The term above describes the picture : 





Pictures can be imported from external applications through the clipboard or from resource files; in 
both these cases they are treated as elementary pictures with no interna! structure. 


Pictures are displayed in graphics windows using the primitive add_pic, which associates a 
named picture's description with a graphics window and simultaneously displays the picture in the 
window. The picture description is permanently associated with the window so that whenever the 
window is scrolled or needs refreshing, the picture can be redrawn. (You can also draw 
‘temporary’ pictures by calling draw_pic). 


Pictures can be displayed in dialogues by giving their picture description as the field descriptor for a 
pbutton or pcheck item of the dialogue (see the chapter on Advanced Dialogues). 


NOTE | 
The first time you use a graphics primitive in any MacPROLOG session, the Graphics Boot 


program must be loaded. This is done automatically for you, and a banner is displayed whilst it is 
being loaded. Thereafter all the graphics primitives remain resident in memory. 
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23.2 The Default Graphic Window 


Using add_pic without naming a graphic window will associate the picture with the Default 
Graphic Window. This is a graphic window with Y coordinates ranging from -500 to +500 
and X coordinates ranging from -500 to +500. Any pictures associated with this window can be 
scrolled either vertically or horizontally, as with all graphic windows. 


Unlike most other graphic windows, it has no visible graphic tools, but it does have a selector 
associated with it, which allows selection of pictures in the window either by clicking over them 
with the mouse, or by dragging a grey rectangle around them. This latter method is a very 
common activity in graphics window, and we shall from here on refer to this as dragging a marqul. 


You can also edit the pictures in the window using the Edit menu commands (e.g. Clear, Cut, 
Paste, Select alj). 


III 
[] 


Default Graphic Window 
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23.3 Overview of QuickDraw 


Graphics on the Macintosh is implemented by a set of low level graphics procedures called 
QuickDraw. an understanding of which will help in using MacPROLOG's graphics. This section 
gives a brief overview of the main ideas behind QuickDraw. 


All information about location, placement, or translation is specified by the programmer in terms of 
coordinates on a plane. The coordinate plane is a two-dimensional grid, as shown below. 











-32768 
-32768 «< So > 32767 


32767 


Coordinates must be integers in the range -32768 to +32767. The coordinate origin (0,0) is in the 
middle of the grid. As in traditional coordinate systems, the horizontal coordinates increase as you 
move from left to right, but. unusually for mathematical systems, the vertical coordinates increase 
as you move from top to botom. 


On the coordinate plane there are 4,294,967,296 unique points. Each point is at the intersection of 
a horizontal grid line and e vertical grid iine. As the grid lines are infinitely thin, a point 1s 
infinitesimal. 


Of course there are more points on this grid than there are dots on the Macintosh screen: when 
using QuickDraw you associate small parts of the grid with areas on the screen. 


Shapes, lines, points and tex: are drawn in this large coordinate plane and are then mapped and 
clipped by the graphics system to the actual graphics window on the screen. 
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23.4 QuickDraw in MacPROLOG 


What follows is a very brief discussion of how graphics is implemented in MacPROLOG: many 
details are necessarily omitted here, but full explanations and numerous examples are given in the 
chapters that follow. 


23.4.1 Graphic Windows 


In MacPROLOG, graphical objects are displayed in Graphic Windows. Each graphic window has 
associated with it a small part of the QuickDraw coordinate plane described above. You can specify 
how much of the coordinate plane you wish to use for each window - this is the window's 
“drawing area". Each graphic window displays on the screen a portion of its drawing area. You can 
roam around this drawing area using the window's scroll bars. 


For example, as mentioned above, the Default Graphic Window's drawing area ranges 
from -500 to +500 in each direction. This means that if you draw something at ( 1000, 1000) in the 
window you won't ever see it! However, an object drawn at (300,300), say, can be brought into 
view on the screen using the window's scroll bars. 


When you create a graphic window, (using the wecreate primitive), you specify how large a 
drawing area you want for that window. You can subsequently change this size either 


programmatically or using the Window deta ils dialogue from the Windows menu. In the 
Graphic Windows chapter there is a discussion of the effects of choosing different sizes of drawing 
area. 


23.4.2 Coordinates, Points and Pixels 


The drawing area of a graphic window is always centered on the coordinate plane at (0,0). When a 
new graphic window is created, the point (0,0) is displayed at the top left hand corner of the 
viewing pane. 


Although a ‘point’ in QuickDraw is defined theoretically, you can think of points as equivalent to 
pixels. 7 


In MacPROLOG, a point is specified as 
(top, left) 


where top is the vertical coordinate and left is the horizontal coordinate. (Remember that vertical 
coordinates increase in a downward direction.) 


A rectangle is defined by specifying the position of its top left hand corner, together with its depth 
and width. Rectangles are represented in MacPROLOG by terms of the form 


box (top, left, depth, width) 


where (top, left) is the coordinate of the top left hand corner, and depth and width are the 
number of points in the vertical and horizontal directions respectively. 
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24 Graphic Description Language 


A graphic window or dialogue can have any number of individual pictures. These are described by 
compound terms constructed from the various picture descriptors and transformers in 
MacPROLOG's own declarative Graphic Description Language (GDL). 


The graphic description language can be broken down into three main sections: 
1) The elementary picture descriptors (e.g.box, circle etc). 


These descriptors describe elementary pictures. They usually have arguments which are the 
coordinates of where the elementary picture is to be drawn. For example the term 


box (10, 20, 30, 40) 


represents a box whose top left hand corner is at (10, 20) and, whose depth is 30 units and width 
40 units. There are 17 predefined elementary picture descriptors and programmers can define new 
ones. 


Note: The predefined picture descriptors are nor the same as predefined predicates. Pictures canno: 
be constructed by direct calls to the picture descriptors. Tney are constructed by passing a GDL 
picture description as an argument to an add_pic call or to a dialogue construction call. 


2) The transformation descriptors ( e.g trans, scales, thin). 


Transformation descriptors modify the description of a picture rather than descnbe a picture 
explicitly. They usually take as an argument a term describing the picture which is to be modified 
or transformed in some way. 


For example, the transformational descriptor grey takes a picture as an argument and fills it with 
grey, So the term 


grey (filloval (100,100, 20,40) ) 


represents an oval filled with a grey pattern (instead of the default black pattern). Other 
transformation descriptors allow pictures to be shifted and scaled, the pen’s colour and size to be 
changed and the fill patterns to be modified. Transformation descriptors can be nested to an 


arbitrary depth. 
3) Picture aggregation. 
A picture can be described as an aggregate of several sub-pictures by grouping the sub-piciures into 


a list. When an aggregation is drawn, if the sub-pictures overlap, then the later sub-pictures are 
drawn on top of the earlier ones. For example the term 


[box (10,20,30,40), grey (filloval (100,100,20,40))] 
represents a box and a filled oval. 
(Note: QuickDraw does not always correctly calculate the area enclosed by aggregations when they 
contain overlapping sub-pictures. This may lead to unexpected behaviour in selection and dragging 


tools. In particular it is not recommended to use aggregate pictures which contain totally 
overlapping sub-pictures. ) 


24 : Graphic Description Language 


EXAMPLE 1 


The bike program defined in the program window below will draw a bike in the Default 


Graphic Window as six separate picture entities, because there are 6 calls to add_pic. Each 
picture is a separate logical object. These pictures are 


handlebars, framel, frame2, bacx wheel, front_wheel and seat 
Each can selected and manipulated independently from the others. 


The bike is drawn with the call bike. 
















é File Edit Find Windows Fonts Eval 


| dd a bike to a graphics windo i 
bike: - 


He ee ee ae co 

add pic(frame1,pensize(2.3,lines([ (96.100). (138,89), (96,100) |] 
))). 

jadd_pic(seat,box(84,172,4.16)). 

add pic(frame2, pensize(2.3.lines([ (140,190), (140,140). (96,100 
4), (96,174), (140,190), (140,440). (86,189)]))). 
jyadd_pic(front_wheel,[oval(1326. 86.8.8), oval(110, 60,60.60)]). 
| add _pic(back_wheel, [oval(126,186.8,8),oval(i110,160.60,60)]). 







cox, arc; lines, and oval are elementary picture descriptors. 


thin, double, pensize, blacx, blackzen are transformation descriptors. 
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EXAMPLE 2 


An alternative definition, using only one call to add_pic, draws the same picture as one picture 
aggregate. Though the bike picture looks the same, the difference is that now the bike is one 
logical structured picture, and the operations of selection, dragging, and ‘get information’ will now 
treat the bike as one unit. 


The bike is drawn with the call whole_bike. 


F 


le Edit Find Windows Fonts Eval 


add & bike to a graphics window 


#3 whole_bike:- 
‘Jadd_pic(the_whole_bike.[arc(85,95.15, 20,160,200). 

pensize(2,3,lines({ (96,100), (138,89), (96,100)))). 
box(84,172,4.16) pensize(2,2,.lines({ (140,190), (140,140 
), (96,400), (96,474), (440.190), (140,140), (86,180)])). 
oval (136,86,8.8}, oval(110,60,60,60),oval(136, 
186,.8,.8). oval(t2it.160,60.60)]). 


Default Graphic Window 


Hawa a 
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EXAMPLE 3 


The same bike could be displayed in a dialogue by having its graphical description as the field 
descriptor of a pbutton or pcheck format item (see the chapter on Advanced Dialogues). 


This is shown in the example program below. 





é File Edit Find Windows Fonts Eval 















add a bike to a graphics window 


YA dikedescription({arc(85,95,15,20,160, 200), pensize(2,3.lin 
MA es({ (96.100). (138,89). (96,100)])).box(84,172, 4.16). pensiz 
Yyae(2,3,lines({ (140.190), (140,140), (96,100), (96.174), (140.1 
Z 90). (140,140), (86.180)j)).0val(136, 86.8.8). o0val(110,60,60 


,60),0val(136,186.8,8). oval(110,160,.60,60)]). 


bikedialog (Button) :- 

bikedescription(Desc), 

dialog(‘Bike in Dialog’ ,150,.50,140.180, 
[ button(10, 10. 20, 60,'Ok'), | 

button(10,110, 20, 60,‘Cancel' ). i 

pbuttoy/4n Aon 16 Button). 





sasari eA ne sa 





a ed ' 
-a oye 

he al -i - 
x te PE 


pang tiewee 


Cancel 


Me eae 


say heres net os 
Awe A 
“J 
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24 : Graphic Description Language 


The elementary picture descriptors 


Elementary picture descriptors describe two types of pictures: hollow and filled. 


A hollow picture has an outline only, drawn in a particular pen. The default pen pattern is black, 
its default size is thin, and its default mode is paint. These defaults can be changed by 
applying a picture transformation. Pictures underneath a hollow picture remain visible; the centre 
of a hollow object is transparent 


A filled picture has both an outline and an interior. This interior is filled using a fill pattern. The 
default fill pattern is black, and can be changed by applying a picture transformation. Pictures 
underneath a filled picture do not remain visible; the centre of a filled object, even if it is filled with 
white, is non-transparent. 


So while 


box (10, 20, 30, 40) 
and white (filibox (10,20, 3C, 40) ) 


describe similar looking objects, they affect the appearance of pictures underneath them in differen: 
ways. 


Remember that the elementary picture descriptors that follow cannot be called directly; they car 


only be used as components of picture terms which are passed as arguments to other Graphics 
primitives such as add_picordraw_pic. 


24.1 box - a hollow ( optionaliy round cornered) rectangular box 


box(top,left, depth, width) 
box (top, left, depth, width, ovaldepth, ovalwidth) 


ARGUMENTS 
top : integer, top edge of box 
left : integer, left edge of box 
depth : integer, depth of box 
width : integer, width of box 
ovaldepth : integer, height of oval for rounding of corners 
ovalwidth : integer, width of oval for rounding of comers 
USES 
1. Four argument use 


To describe a hollow rectangular box. By default, the box has a thin black outline, which can be 
modified using a transformation descriptor. 
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For example, box (20, 20,110,180) describes: 


and thick (grey (box (20,20,112%,180))) describes the same rectangle but with a thick 
grey outline. 


2. Six argument use 


To describe a hollow round cornered rectangular box. ovalder= and ovaiwidth specify 
the diameters of curvature for the corners. These arguments specify an oval, whicn determines the 
‘roundedness' of the corners. By default, the box has a thin black outline. 


ovalwidth | ovaldep 2.2 


(When a rounded corner rectangle is drawn, the ovals inside the comers are not actuaily drawn.) 
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24 : Graphic Description Language 


EXAMPLES 


The following rounded rectangles each have same depth and width for their rectangular 
dimensions, but have differing ovaldepth and ovalwidth. 


30,30 30,70 


JL 
J 


10730 70,70 


24.2 fillbox -a filled (optionally round cornered) rectangular box 


fillbox (top, left, depth, width) 
fillbox(top,left,depth,width, ovaldepth, ovalwidth) 


ARGUMENTS 

top : integer, top edge of box 

left : integer, left edge of box 

depth : integer, depth of box 

width : integer, width of box 

ovaldepth : integer, height of oval for rounding of comers 

ovalwidth : integer,width of oval for rounding of corners 
USES 

i men 


To describe a filled rectangular box. By default, the box has a thin black outline and is filled with 
black, which can be modified using a transformation descriptor. 
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For example, 


£31 25ox620720;-2:10;, 160) 
describes: 





and check (fillbox(Z5,20,110,280)) describes the same rectangle but with a checked 
interior. 


2. Six argument use | 

To describe a filled round cornered rectangular frame. ovaldepti and ovalwidth specify 
the diameters of curvature for the corners, as before. By default, the oval has a thin black outline 
and is filled with a black pattern. Both can be modified using transformation descriptors. 


For example, 


grey (double (fi llbox(2C,20,110,180, 70, 70))) 


describes: 





where grey sets the fill pattern to grey, and double doubles the size of the pen, giving a thicker 
black outline. 
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24.3 oval- a hollow oval 


oval (top, left, depth, width) 


ARGUMENTS 
top : integer, top edge of oval's enclosing box 
left : integer, left edge of oval's enclosing box 
depth : integer, depth of oval 
width : integer, width of oval 

USE 


To describe a hollow oval which just fits in the rectangular frame specified by the arguments. If the 
frame is square then this gives a circle. By default, the oval has a thin black outline. 


For example, 
double (oval (2C, 20,100,230) ) 


describes 


he 


The double transformation gives the oval a thicker outline. 


(The dotted rectangular frame will not be drawn, but here it indicates the frame into which the oval 
fits.) 
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24.4 filloval - a filled oval 


filloval (top, left, depth, width) 


ARGUMENTS 
top : integer, top edge of oval's enclosing box 
left . tinteger, left edge of oval's enclosing box 
depth : integer, depth of oval 
width : integer, width of oval 

USE 


To describe an oval which just fits in the rectangular frame. If the frame is square then the oval is a 
circle. By default, the oval has a thin biack outline and is filled with black. The defaults can 22 
modified using transformation descriptors. 


For example, grey (filloval(27,2Z%,100,227)) describe 





(The dotted rectangular frame will not be drawn, but here it indicates the frame into which the ovel 
fits.) 


24.5 circle -a hollow circle 


circle(ycentre,xcentre, radius) 


ARGUMENTS 
ycentre : integer, vertical centre of circle 
xcentre : integer, horizontal cenrre of circle 
radius : integer, radius 

USE 


To describe a hollow circle centred at (ycentre,xcentre) and ofa given radius. By 
default, the circle has a thin black outline. 
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For example: circle (75,110, 60) describes: 


50 
i 135 
170 


(The dotted rectangular frame will not be drawn, but indicates the frame into which the circle fits.) 


24.6 fillcircile -a filled circie 


fillcircle(ycentre, xcentre, radius) 


ARGUMENTS 
ycentre : integer, vertical centre of circle 
xcentre : integer, horizontal centre of circle 
radius : integer, radius 

oe 


To describe a circle centred at (ycentre, xcentre) and of a given radius. By default, the 
circle has a thin black outline and is filled with black. The defaults can be modified using 
transformation descriptors. 


For example, 


greypen (pensize(3,3,brick (fillicircie (75,110, 60)))) 
describes 





135 
170 


where brick sets the fill pattern to a brick like pattern, greypen sets the pen pattern to grey, and 
pensize sets the size of the pen. 
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24.7 square -a hollow square frame 


square (ycentre,xcentre, size) 


ARGUMENTS 
ycentre : integer, vertical centre of square 
xcentre ` : integer, horizontal centre of square 
size : integer, size of sides of square 
USE 


To describe a hollow square centred at (ycentre,xcentre) and with sides of given size. 
By default, the square has a thin black outline. 


For example, 
square (75,116,120) 


descnbes: 


50 
I5 


LO 
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24.8  fillsquare -a filled square 


fililsquare (ycentre,xcentre, size) 


ARGUMENTS 
ycentre : integer, vertical centre of square 
xcentreE : Integer, horizontal centre of square 
size : integer, size of sides of square 
USE 


To describe a square centred at (ycentre,xcentre) and with sides of a given size. By 
default, the square has a thin black outline and is filled with black. 


For example, 
horiz (fillsquare (75,110,120) ) 


cescribes: 





135 
T70 


where horiz sets the fill pattem to a horizontal pattern . 
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24.9 arc -a hollow arc 


arc (top,left, depth, width, startangle,arcangle) 
ARGUMENTS 


top : integer, top edge of oval's enclosing box 
left : integer, left edge of oval's enclosing box 
depth : integer, depth of oval 

width : integer, width of oval 

startangle : integer, beginning of arc 

arcangle : integer, degrees clockwise 


USE 

To describe an arc as a pie-segment of the oval defined by top, aafe; depth, width. 

The size of this segment is determined by the startangle, arcangle arguments, where 
startangle indicates the angle at which the arc begins and arcangle defines the angular 


extent of the arc. Angles can be given in positive or negative decrees, where a positive angle goes 
clockwise, and a negative angle goes counter-clockwise. 


A startangle of zero degrees is at 12 o'clock high, 90 ( or -270) at 3 o'clock, 180 ( or -1&° 
at 6 o'clock and 270 ( or -90) is at 9 o'clock. 
By default, the arc has a thin black outline. 


Example; thick (are(20720,130,.200,1357220).) descavces: 





Startangle 


as arecangle Jesss 
110 


where the dotted rectangle is an indication of the rectangle into which the complete oval would fit, 
and the thick transformer sets the pen to a size of 8*8 pixels. 
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24.10 wedge -a filled arc 


wedge (top, left, depth,width, startangle,arcangle) 
ARGUMENTS 


top : integer, top edge of oval's enclosing box 
left : integer, left edge of oval's enclosing box 
depth : integer, depth of oval 

width : Integer, width of oval 

startangle : integer, beginning of wedge 

arcangle : integer, degrees clockwise 


USE 

To describe a filled arc as a pie-segment of the oval defined by top, left, depth, width. 

The size of this segment is determined by the startangle, arcangle arguments, where 
startangle indicates the angle at which the arc begins and arcangle defines the angular 


extent of the arc. Angles can be given in positive or negative degrees; where a posinve angle | goes 
clockwise, and a negative angle goes counter-clockwise. 


Astartangle of zero degrees is at 12 o'clock high, 90 ( or -270) at 3 o'clock, 180 ( or -180) 
at 6 o'clock and 270 ( or -90) is at 9 o'clock. 

By default, the wedge has a thin black outline and is filled with black. 

For example, 


thick (boxed (wedge (20, 20,130, 200,135,110) )) 


describes 





See a Cang le “S-s> 
10° 


where boxed sets the fill pattern to be a box-like pattern and the dotted rectangle is an indication of 
the rectangle into which the oval segment fits. 


Note: The radii lines of the segment are not drawn. 
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24.11 lines -connected lines 

lines (listofpoints) 
ARGUMENT 

listofpoints : list of points 
USE 


To describe a sequence of joined lines between the points in the listofpoints. By default, the 
lines will be drawn in a thin black line. 


The list of points is of the form 
[(yO,x0),(yl1,x1), ...] 
or 


[[y0,x0],[y1,x1j, -.-] 


where (y,x) iS a point represented by a comma pair 
and [y, x] is a point represented by a two element list 


For example, 


pensize(1,2,lines([((-10,50), (-Z20, 9°), (-.7, 90), (2,62), 
(15,90 )34 20,7 90) oS 250) ¢ 20750) I) 


describes 
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24.12 poly -an enclosed object of connected lines 
poly (lListofpoints) 
ARGUMENT 
listofpoints : list of point pairs 
USE 


To describe a closed sequence of joined lines between the points in the listofpoints. By 
default, the lines will be drawn in a thin black line. 


The list of points is of the form 
yO. 20 Gest aie) 
or 
(ives xO] e viek] y 2654 


where (y,x) isa point represented by a comma pair 
and [y, x] is a point represented by a two element list 


The set of lines will be automatically closed by a line from the last point back to the first point. 
The main difference between Lines and pciy is that polygons can be inverted. 


244 


24 : Graphic Description Language 


24.13 £#illpoly -a filled enclosed object of connected lines 


fillpoly (listofpoints) 


ARGUMENT 
listofpoints : list of points 
USE 


The same as poly except that the area enclosed by the set of closed lines is filled with the fi! 
pattern, which by default is black. 


The system will add a line from the last point back to the first point. 
EXAMPLE 1 | 
lgrey (fillpoly(((119,24), (120,22), (1,265), 


| (2,36) (225,208) Ss) 144) 19) 
describes 
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EXAMPLE 2 


alpha (fillpoly([(155,-16), (94,160), (84,-26), (153,134), 


(29,45), (=9;, 294), (-30, 96), (56,254), 
(~39,226), (154,-18)])) 


describes 





Tne Macintosh fills polygons by counting each line in the list of lines defining the polygon as a 
poundary line. Then, as it traverses each boundary line it toggles the filler on/off. So, in these two 


examples above, the polygons have lines that cross each other and they therefore have some 
unfilled interior areas. 
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EXAMPLE 3 


greypen (diamonds (fillpoly([(50,-29), (125,50), (125,150), 
(50,220); (2.5% 250) 74-25; 50) 177) 





describes 
9 2$ 9949694606005 % 
EX AMPLE 4 
grey (fos tooly( [(111,310),(224, 510), ee SOG by bo 06,304 )-4 4225; 
(Tee SOL veils See el wy SOETERS peg ae bps fee oe 
CER 48s 2 Oye tle ge 0) 4 toe eS oo) GAS yoo) yp (Oyeec eG) 
(266,257) ¢(264,41 6) 3S pel Oly foe A 7g le eels 


(6, G42) yp tee. ese) eera Lore 


describes 
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24.14 text -a text display 


text (font, size, face, ypos, xpos,text) 


ARGUMENTS 
fontname : atom, name of font 
fontsize : integer, point size 
fontface : integer, face details 
ypos : integer, vertical position of bottom of first character 
xpos : integer, horizontal positon of first character 
text : atom, text to enter 
USE 


To describe a text display in a particular font, face and size and with the bottom left end of the first 
character at (ypos, Xpos). 


The fontname is 'Times', 'Covrier', 'Geneva', 'Helvetica' or any other font 
supported by your system disk. 


The fontsize is 10, 12, 14, 18, 24 


The fontface canbe 


0 for Normal 

l for Bold 

2 for Italic 

4 for nderlin 

8 for Outline 
16 for Shadow 


This can be combined by addition, resulting in a composite type face 


eg1+2+16=19 Tealie + Bold + Shadow 
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24.15 textbox -a text display in a box 


textbox (font, size, face,t,1,d,w, just, text) 


ARGUMENTS 
font : atom, name of font 
size : integer, point size 
face : integer, face details 
t : integer, top edge of box 
1 : integer, left edge of box 
d : integer, depth of box 
W : integer, width of box 
just : integer, text justification 
text : atom, text to display 
USES 


To describe a text display in a particular font, face and size, placed ina box, with the first 
letter positioned in the top left hand corner of the box, and carriage returns automatically inserted as 
required (see the description of text for details of fent, face and size). 

The box outline will not be drawn. 


The just argument determines how the text is justified within the box. It may be 


( for left justified text 
-1 for night justified text 
1 for centered text 


As an example: 


Pex dox(*Chica06 7 12).0 7-164, pecoreeer vy 

'Eere is an example of some text in a box. It is Chicagce, 
mormal, and size 12.~MYou can insert carriage returns, and tyre 
cast the end of the box, in which case you will only see une text 
shat is in the box ') 


describes: 


‘Here is an example of some 
text in a box. it is Chicago, 
normal, and size 12. 

You can insert carriage 
returns, and type past the 
end of the box, in which 


case you will only see the 
taut that ic in tha hay 


The font is Chicago 12 point, and the just argument is 0 so the text is displayed with left 
justification. 


249 


24 : Graphic Description Language 


The picture below is of a text box drawn on top of a filled box. As can be seen, the empty parts of 
the text box appear white, and obscure any picture underneath. 


X xx COX. 6.6. + “wil SA S Nd $. av ‘oe So Né a? ae + : N 
CPR IPR LI SOIR I 
DR III nS 
SOON RARRARAKRRARAR ALE S&S 
“> + -4 » oa E e N 
Swen Some text in a 2I 
. . . + A >. . + 
© © © @ A VA Ae Ae ae 
SO large box, on top 2atess 
Renean OT a filled Dox ony 
EEEN RERS 
AAA EAA A 


A A 

A EAA OLY 

LIN nae) 

POSE OO CO Oe 

eee tetera te a asa aa a a ease: 

TORRAIN OD COMO OLS OK 
yyy By 


* 


24.16 icon -an icon defined by two ‘hexadecimal strings’ 


icon (top, left, depth,width, hexi1, hex2) 
icon(top, left, depth,width,icon_details) 


ARGUMENTS 

top : integer, top edge of icon 

left : integer, left edge of icon 

depth : integer, depth of icon 

width : integer, width of icon 

hex] : atom, comprising 128 hexadecimal] characters 

hex2 : atom, comprising 128 hexadecimal characters 

icon details : resource number of icon, or term identifying resource icon 
USES 
1. Six argument use 


To describe an icon represented as two atoms of 128 hexadecimal characters, where in the four-b:t 
binary representation of each hex character. O represents a white pixel and 1 represents a blacx 
pixel. An icon is a grid of 32 x 32 pixels. One row of the icon is represented by eight hexadecima: 
characters. The two atoms of 128 four-bit characters represent the 1028 individual pixels that are 
needed to define an icon. The first atom encodes, row-wise, the top half of the icon, and the 
second the bottom half. | 


Examples of rows: 


‘00000000' completely white 
'33333333' grey 
'FFFFFFFF completely black 
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ICON EXAMPLE 
Suppose that 
Hexl = 


'00102000001860000714A38002522D00012012000080040000400800007FF80000 
20100000201 000001 FEOO00008 40000008 40000008 40000008 400000084000", 


and 
Hex2 = 


'0008400000084000000840000008400000084000003FF000002010000920100009 
FFFC0001800600030003000200010007FFFF8007FFFF800000000000092000'. i 


The description 


icon (0,0,32,32, Hexl, Eex2) 


describes the icon 


X 


icon (0,0,200,200, Hexi, =ex2) 


and the description 


describes 





The 32x32 bit image of the icon is scaled and shifted to fit into the rectangle enclosed by 
(top, left, depth, width). To guard against possible distortion of the bit image, it 1s 
advisable to ensure that this rectangle’s height and width are both multiples of 32. 


NOTE: The reason why we need two atoms of hex digits rather than one, is that the maximum 


length of an atom is 255 characters. However, 256 digits are needed to fully encode the 32x32 bit 
image. 
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2. Five argument use 
To describe an icon which exists in a resource file. 


icon details indicates a (resource) icon on disk. It is a term of the form: 


(i) resourceid 


or (i) resource (name) 

or (111) resource (name, file) 

or (iv) resource (name, file, volume) 

or (v} resource (number) 

or (vi) resource (number, file) 

or (vii) resource (number, File, volume) 


The icon is scaled to fit the rectangle defined by top, left, depth, width. 


The following icons from MacPROLOG 2.0 and the Macintosh System (Version 5.3) are always 
available, and have the following resourceids : 


aA «a p 





1000 1001 1002 
@ 28 p 
1003 1007 0 | 1 2 
Xi 
1008 1009 


You can get a complete list of all the icons currently available in the system using the res_items 
primitive (see the chapter on Resources). 
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24.17 picture -a QuickDraw picture 


picture (top, left, depth,width,picture details) 
ARGUMENTS 


top : integer, top edge of picture 
left : integer, left edge of picture 
depth : integer, depth of picture 
width : Integer, width of picture 


picture details : term identifying resource picture 
USE 


To describe a picture imported from a resource file. All imported pictures can be repositioned ard 
rescaled by changing the rectangle into which the picture is to be drawn, and the picture will be 
expanded or shrunk as needed. 


The picture details argument may be as follows. 


(a) A (resource) picture on disk. It is a term of the form: 


(1) resource (name) 


or (ii) resource (name, file) 

or (ii) resource (name, file, volume) 
or (iv) resource (number) 

Or (v) resource (number, fils) 

Or (vi) sesource (number, file, volume) 


Resource pictures can be loaded from resource files and then crawn as QuicxDraw pictures. 
Resource pictures are stored in the resource forks of files, and always have associated with them an 


` 


identifying number, and often an identifying name. They can be referenced by either attnbute. 
Before drawing a resource, its resource file must be opened. 


In the two cases where the file name and volume are given in the sicture deceiis, the file is 
automatically opened, if found. | 


In the two cases where the file name but not the volume is given in the picture zetails, the 
file is automatically opened and assumed to be on the default volume. 


In the two cases where the file name is not given, the onus is on the programmer to ensure that the 
resource file is currently open (e.g. by using the res_open primitive; see chapter on Resources). 


Displaying a QuickDraw equivalent of some complicated GDL picture is much faster than 
displaying the description. If an application is going to display some complex GDL picture 
frequently, then it is more efficient to construct a QuickDraw picture from the GDL description, and 
then use the picture primitive to display it. The save_pic primitive allows you to save a GDL 
description as a resource picture. 
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. The following resource picture is available to you as it originates from the Macintosh System 
Folder, and can be described by 


picture (10,10, 50,150, resource (-15968) ) 
OT picture (10,10,50,150, resource (~15968, system) ) 


© By a Sg 


Although this picture looks like several pictures, it is treated as one object. To display just part of it 
would require aggregating it with some filled white boxes to hide those parts of the picture not 
required. 


(b) A clipboard picture. piccure_details isa term of the form 
clirvboard ('number') 


If you Cut or Copy a picture into the Clipboard using the Quickdraw format, and then 


Paste it into a graphics window, the description of the picture added to the data base of the 
craphics window will be a picture term, where the picture_detaiis argument is a term of the 
form 


clipboard ('number') 


and number is automatically generated by the system. This picture is added by the system to the 


graphics window into which the Paste took place, using add_pic, and is then treated as one 
logical unit. A name for the picture is automatically generated. 
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Transformation Descriptors 


A transformation descriptor does not directly specify a visible object, rather it modifies the 
appearance of any picture defined within its scope. Any picture descriptions which are not 
enclosed by the descriptor are unaffected. 
Transformation descriptors can be used in combination, e.g. 
check (fillbox(10,20, 220,140) ) 
describes a box filled with a checked pattern, 
greypen (check (fillbex(10,20,120,140))) 
describes a box filled with a checked pattern, and drawn with a grey outline, and 
thick (greypen (check (fiilbox(10,20,130,140)))) 
describes the same box but drawn with a thick grey pen. 
In the case of conflicting descriptors, the outermost descriptor has priority, e.g. 
diag (thick (greypen (check (fillbox(10,20,1=20,140))))) 


represents a box as drawn below. 





where the descriptor diag has overridden the descriptor check in determining the fill pattern. 
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24.18 trans -translate a picture 


trans (down, across, picture) 


ARGUMENTS 
down : integer, vertical translation 
across : integer, horizontal translation 
picture : a picture description 

USE 


To translate a picture by down vertically and across horizontally. This is an inexpensive 
mapping since only the logical origin of the picture is affected. Pictures can be translated in both 
positive and negative directions. 
For example, 

[box (10, 20, 30, 40) , greypen (trans (20, 30 (box (10,20,30,40))))] 


describes the following picture: 


24.19 scale - scale a picture 


scale(vertscale, horizscale,v_org,h_org, picture) 
scale(vertscale,horizscale, picture) 


ARGUMENTS 
vertscale > : number, vertical scaling factor 
horizscale : number, horizontal scaling factor 
v org : integer, vertical origin of scale 
h org : integer, horizontal origin of scale 
picture ; a picture description 

USE 


To scale a picture by a factor of vertscale vertically and horizscale horizontally. The 
scaling is performed relative to the given origin of scale (v_org, h_org). In the three argument 
form, the scaling is done about (0,0). 


By scaling about the local centre of a picture, one can expand (or shrink) the picture whilst its 
centre stays fixed. You can find a picture's centre using the pic centre primitive (see the 
chapter on Picture Manipulation). Scaling about any other point will have the effect of moving the 
picture's centre. 


Note that scaling factors less than 1 will shrink a picture. The scaling also affects the pen size, and 
if this causes the pen's depth or width to be less than 1, the pen becomes invisible. 
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EXAMPLE 1 


The centre of both boxes below is (25,40). By scaling the second box about this origin, we have 
scaled in place. 


[greypen (box (10, 20,30,40)),scale(2,3,25,40,box(10,20,30,40))] 


EXAMPLE 2 


Both boxes below have their top, left hand comers at (10,20). By scaling the second box about 
this origin, we have ‘stretched’ it and kept the top left hand corner fixed. 


[greypen (box (10,20,30,40)),scale(2,2,10,20,box(20, 20,30, 40) ) | 


EXAMPLE 3 


The imported picture displayed in the first A graphic window on the next page is described 
by 


picture (150,115,180, 346, rescurce (456026, mypictures) ) 


The vertical coordinate of its centre is (150 + 180/2), and the honzontal coordinate of its centre !s 
(115 + 346/2) 1e. at (240,288). 
(The picture is stored in a resource file called mypictures). 


Introducing the scale descriptor and changing its description to 


scale (2,3,240,288, 
picture (150,115,180, 346, resource (456096,mypictures) )) 


enables us to obtain the second picture shown below. 
Notice that the vertical scaling factor is 2 whilst the horizontal scaling factor is 3, and therefore the 


picture has been ‘stretched’ more in the horizontal direction than in the vertical direction, as can be 
seen by a close examination of the bubbles? 
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The Pen 

The outline of all elementary pictures is drawn in the current pen. This pen has three attributes, 
pensize, penpattern and penmcce, all of which can be transformed using the built-in 
system descriptors or user-defined forms. 

The Pen's size 

Pen size transformers fall into two categories: absolute and relative. 

Absolute transformers reset the pen to a certain fixed size regardless of what its present size 1s. 
This means that they ignore other pen size descriptors which fall within their scope, in a simular 


way to penpattern and fillpattera transformers. 


For example: 
pensize (2,3, double (<nick (box (15,20,30,49)))) 
represents a box drawn in a pen whose cimensions are 2 pixels deep, and 3 pixels wide. The fact 
that thick occurs inside pensize means itis ignored. This enables you to prefix any picture 
description with an absolute pen size and ensure it is drawn in the pen you want, regardless of its 
description. 
Relative transformers change the pen relative to its present description. 
For example, if the current pen size is 1 x 1 pixels, 
Taicker(2,3,.c0x(10).. 720,407. 
represents a box drawn in a pen whose ¢:mensions are 3 pixels deep. and 4 pixels wide. and 
“hicker (2,3,thickezr:2,3,box(i°,20,30,40))) 
represents a box drawn in a pen whose cimensions are 5 pixels deep, and 7 pixels wide. 


NOTE 


If a pen size transformer causes the pen’s size to become less than 1, the pen will become invisibie. 


259 


24 : Graphic Description Language 
Absolute pen size transformers 


24.20 thin -set pen to 1x1 pixels in size 
thin (picture) 
ARGUMENT 
picture : a picture description 
USE 


To set the size of the pen to 1 x 1 pixels. This is actually the default pen size. 


24.21 thick - set pen to 8x8 pixels in size 
thick (picture) 
ARGUMENT 
picture : a picture description 
oe 


To set the size of the pen to 8 x 8 pixels. 


pa nilpen - set pen to 0x0 pixels in size 


nilpen(picture) 


ARGUMENT 
pl e2tre : a picture description 
USE 


To set the size of the pen to O x O pixels, i.e. invisible. This means that filled objects have no 
outline, and hollow objects are invisible. The combination of 


niipen (box(....)) 


is sometimes useful for ‘framing’ pictures, i.e. giving them a fixed but invisible outline that might 
affect their behaviour with graphic tools. 
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24.23 pensize -set pen to user defined size 


pensize (depth, width, picture) 


ARGUMENTS 
depth : integer, depth of pen in pixels 
width : integer, width of pen in pixels 
picture : a picture description 

USE 


To set the size of the pento depth x width pixels. 


Relative Pen Size Transformers 


24.24 thinner - decrease the size of the pen 


thinner (depth, width, picture) 


ARGUMENTS 
dept : integer, depth decrement of pen in pixels 
width : integer, width decrement of pen in pixels 
picture ; a picture description 

USE 


To decrease the size of the pen by the given depth and width.. 


24.25 thicker - increase the size of the pen 


thicker (depth, width, picture) 


ARGUMENTS 
depth : integer, depth increment of pen in pixels 
width : integer, width increment of pen in pixels 
picture : a picture description 

USE 


To increase the size of the pen by the given depth and width. 
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.24.26 double - double the size of the pen 
double (picture) 
ARGUMENT 
picture : a picture description 
USE 


To double the pen's current depth and width. 


24.27 triple -triple the pen's size 

triple (picture) 
ARGUMENT 

picture : a picture description 
USE 


To triple the pen's current depth and width. 


24.28  penscale -scale the pen 


penscale (vertscale, horizscale, picture) 


ARGUMENT 
vertscale - number, vertical scale factor 
horizscale : number, horizontal scale factor 
picture : a picture description 

USE 


To scale the size of the pen by the vertscale and horizscale factors, i.e. the pen's depth 
is multiplied by vert scale, and the pen’s width is multiplied by horizscale. 


Note that scale factors less than 1 will shrink the pen size, and if the pen size becomes less than 1 
then the pen becomes invisible. 
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The pen's mode 
24.29 penmode - set pen mode 


penmode (switch, picture) 


ARGUMENTS 
switch ‘atom, a defined mode 
picture : a picture description 
USE 


The penmode determines the way the outline of pictures is drawn on the screen. This moce 
specifies one of eight boolean operations 


paint, or, xor, erase, npaint, nor, nxor, nerase 
that QuickDraw is to perform before displaying a new pixel. 
There are four basic operations -- painz, or, xor, and erase. 


The paint operation simply replaces the pixels underneath the pen with the pixels in the source. 
i.e. it paints pixels onto the screen without regard for what is already there, obscuring any images 
below. This is the default mode. 


The or, xor and erase modes wii! ail draw any white pixels as transparent. i.e. drawing iz 
white in any of these three modes has no visible effect on the screen. 

However, when a black pixel is to be crawn, its actual appearance on the screen cerends on i52 
pixel already there. 

The modes display a black pixel as follows: 


or black 
XOX black if the existing screen pixel is white, white if the existing screen pixel is black 
erase white 


Each of the basic operations has a varant in which every pixel in the pen is inverted before the 


operation is performed (i.e. npaint, mor, nxor, and nerase), giving eight operations in 
all. 
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EXAMPLE 1 


In this example, a hollow oval has been drawn over a black filled box using a very large pen 
(described by pensize (20,40, ...)) , anda ‘chunky’ checkered pattern ( described using the 
penpattern descriptor that is explained later in this chapter, with an argument of 
'OFOFOFOFFOFOFOFO'). i 


The four pictures display the different effects of the four positive pen modes, paint, or, xor 
and erase. 


The negated modes are not displayed as they would result in similar images ( this pen pattern iS 
symmetrical }. 





Or erase 
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EXAMPLE 2 
The following eight pictures show how the modes affect the visual appearance of the pen when 
applied to filled objects. This is because when drawing filled objects, the pen pattern is drawn over 
the edge of the filled interior. 
Each picture below is described by 

greypen (penmode (Mode, thick (brick (filloval(0,0,75,150)))})) 


and each picture is labelled by the Mode used. 


paint Xor 





npaint nxor 





aay A yA Mig Py Betty 
whey et ywhghygey * yh wrAyvAe 
A 





nor nerase 
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EXAMPLE 3 


In this example we show how the different pen modes affect the display when a 
thick (greypen(oval)) is drawnovera grey (oval) 


4, OG sure 
CIARA SASSER 
Ley Mar eee: 

a t? 
GA 





nor nerase 
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EXAMPLE 4 


We now look at how combining penmodes with text displays can result in different images. We 
only show the positive modes, as the negated modes for greypen are similar to the positive 
modes, and for blackpen only npaint has any effect and that is the same as erase. 


In these first four pictures the text has been overlayed by a hollow box drawn with a large grey 
pen. 


ae 


Here is some text in a box 
overlayed with a hollow 
box drawn with a very 
large grey pen using xor 
mode 


Here is some text in a DOX 
; overlayed with a hollow 
4 box drawn with a very 


A heey 


4 large grey pen using paint 


Sew SETS SS NE 


> 


as 





i 
; 
! 










Here is some text in a DOH 


overlayed with a hollow ; overlayed with a hollow 

f box drawn with a very box drawn with a very 

: large grey pen using erase 
mode 


This qverlay makes the 
test appear grey 


267 


24 : Graphic Description Language 


In these four pictures the text has been overlayed by a hollow box drawn 
with a large black pen. 


4 Here is some text in a box 
; § overlayed with a hollow 
k box drawn with a very $ e box drawn with a very 


; large Diack pen using painti- ; large black pen using xor 


| jseeiempering anvertssthe * “od 
AMen tee : 





Here is some text in a box 4 Here is some text in a box 
overlayed with a hollow $ overlayed with a hollow 

¥ box drawn with a very J box drawn with a very 

& large black pen usingor W targe black pen using 

$ mode : erase mode 
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NOTES 


(a) The idea of ‘grey’ text is often very useful in dialogues. This can be achieved by having a 
disabled pbutton or pcheck whose picture description contains some text and an overlaying 
grey box whose penmode Is set to erase, asin the following example. 


trial(Text):- 
text_desc(Text,Desc), 
dialog('grey text’,210, 20, 110, 190, 
[ button( 10, 10, 20, 80, Ok}, 
button( 410, 100, 20, 80. ‘Cancel'). 
pbutton( 40. 45, 60, 100. Desc)j. Btn). 


text_desc(Text,Desc):- 

Desc = 

framed_picture(box(0,0,60,100),.[textbox('Chicago’ ,12.0,0.0,60, 
200,Text\,greypen(pensize(50,.50, penmode/erase.5cx(0,0,60,400)) 















Detauit TETT Window 


CO 


y 

here is some E: 
grey fextin a } 
DOH l 
$ 

k 


Hee SEMEN O VECTOR A 


AA ' 





: trialChers `s some cree text in @ box’) 


A An t 


e E E O 
Tigined in greater detail at the 





pie ae the next chapter on Pichie oa 


¿As noted previousiy, when an aggregate picture contains overiapping sub-pictures, QuickDraw 
Soes not always return the correct frame’ for the picture. To overcome this problem we explicitly 
set the Rectangle. We make it the same depth and width as the rectangle of the poutton inthe 
dialogue to ensure that there is no visual distortion in the appearance of the text.) 


(b) In xor mode a hollow picture drawn on top of itself disappears. This is particularly useful 
when writing tools that use dynamic pictures, as one can remove a picture by merely drawing it 
again (see Graw_pics in the chapter on Tool Building). 


Note, however, that the penmode only affects the outline of objects, it has no effect on the interior 
patterns of filled objects. 
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The Pen's Pattern 


The pen's pattern determines how the outline of pictures appear on the screen. Black is the default 
pattern for the pen. 


In MacPROLOG a pattern can be defined by the user using an atom comprising 16 hexadecimal 
digits. 


The Macintosh Control Panel gives an example of how patterns are determined by a grid of 
§x8 pixels. 





In the above diagram, we see a grey pattern defined by an 8x8 pixel grid. Its hexadecimal 
cescription would be 


"RAS SAASSAASSAA5S5'. 
(Biack pixels may be represented by a bina. 1, and white pixels by a binary 0. The top pixel row 


of the above pattern may be representec 5y the binary number 10101010, which is AA In 
hexadecima!. Tne rest of the pattern is repres2n.:2d in a similar way.) 


Deskitcs Pattern 





In the above diagram, we see another pattern defined by an 8x8 gnd. Its hexadecimal 
representation would be 


'R2 3003 1BD8COOCED". 
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24.30 blackpen -set the pen to black 
blackpen (picture) 
ARGUMENT 
picture : a picture description 
USE 


To set the pen’s pattern to solid black. This is the default pen pattern. 


24.31 greypen - set the pen to grev 
greypen (picture) 
ARGUMENT 
picture : a picture description 
USE 


To set the pen's pattem to grey. 


24.32  whitepen -set the pen to white 
whitepen (picture) 
ARGUMENT 
picture : a picture description 
USE 


To set the pen's pattern to white. 
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24.33 penpattern - set pen to user defined pattern 


penpattern (pattern, picture) 


ARGUMENTS 
pattern : 16-character atom representing pattern 
picture : a picture description 

USE 


Sets the pen colour to the nominated pattern. The pattern is specified by an atom which consists of 
16 hexadecimal characters. 


For example, the pattern for diagonal lines is 
'0102040610204080' 


and the description of the object below 1s 


The box outline is drawn in the penpazzern specified above, and the box is filled with the 
pattern rdiag which is a predefined pattern of diagonal lines going in the opposite direction (see 
the section on Fill Patterns below). 
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Fill Patterns 
All calls to filled patterns are of the form 
fill (picture) where fillis one of the following 


black 

brick 

boxed 

check 
crosses 
diag 
diamonds 
grey 

horiz 

igrey 

rdiag 
speckled 
stripesthin 
stripesthick 
waves 

white 

alpha 

beta 


As with all transformers, the outermost fill descriptor will take priority. All fill transformers are 
absolute, there is no notion of 'stripier’ or ‘blacker’. 


There are a certain number of built in patterns, but users can define their own as hexadecimal atoms 
in the same manner as pen patterns. 


: 
Snitetsts 
Sarita 


Desktop Pattern 





The above pattern would be represented by the atom 'DD77DD77DD77DD77". 
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24.34 grey - Set fill pattern to grey 
grey (picture) 
ARGUMENT 
picture : a picture description 
USE 
Sets the fili pattern to grey. 
For example 
grey (fillbox(0,0,46,187:) 


describes 





24.35 lgrey - set fill pattern to light grey 
lgrey (picture) 

ARGUMENT 
picture : a picture description 

USE 

ets the fill pattem to light grey. 

For example 

lgrey (fillbox(0,0,46,-&-)) 


cescribes 
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24.36 boxed -set fill pattern to boxed 


boxed (picture) 
ARGUMENT 

picture : a picture description 
USE 
Sets the fill pattern to boxed. 
For example 

boxed (fillbox(0,0,46,180)) 
describes 





PSP Sets BEE PSS SSessSa te 
EPSPS DEED PES DPSS 


24.37 brick - set fill pattern to brick 
brick (picture) 
ARGUMENT 
picture : a picture description 
USE 
Sets the fill pattern to brick. 
Example 
brick (fillbox(0,0,46,180) ) 


describes 
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24,38 check - set fill pattern to check 
check (picture) 
ARGUMENT 
picture | : a picture description 
USE 
Sets the fill pattern to check. 
Example: 
check (fillbox(0,0,46,186C)) 


describes 





24.39 crosses - set fill pattern to crosses 


crosses (picture) 


ARGUMENT 


-_ 


cture : a picture description 


P 


- 


USE 
Sets the fill pattern to crosses. 
Example 
crosses (fillbox(0,0,4€,1i80)) 


describes 


SEES SEES EEE OE ESS EESEEOESESHESESOESEEESESH FESO YUDS 


SHSHEHEOOOS 
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24.40 diag -set fill pattern to diagonal stripes 


diag (picture) 
ARGUMENT 

picture : a picture description 
USE 
Sets the fill pattern to diagonal stripes. 


For example 


diag (fillbox(0,0,46,180)) 


describes 





24.41 diamonds - sets fill pattern to diamonds 
diamonds (picture) 
ARGUMENTS 
picture : a picture description 
CSE 
Sets the fill pattern to diamonds. 
Example 
Giamonds (fillbox (0,0, 26,180) ) 
describes 


$3 S OOS SS S990 099894599906 
SOO SESSECESS SES PEREE OOS 
PO OSSSSOGSIS GOSS OSOSOSG 


$OOOSOOGSFESSOSHSESH OSS 
POSS SO SSPPIHS IPDS OS SISOS SESE 
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24.42 horiz - set fill pattern to horizontal stripes 
horiz (picture) 
ARGUMENT 
picture : a picture description 
USE 
Sets the fill pattern to horizontal stripes. 
Example 
horiz(fillbox(0,0,46,1i€<)) 


describes 





24.43 rdiag - set fill pattern to reverse diagonal stripes 
rdiag (picture) 

ARGUMENT 
picture : a picture description 

USE 

Sets the fill pattern to a reverse diagonal stripes. 

Example: 
raiag(fillbox(0,0,46,1&°)) 


describes 


Yj 
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24.44 speckled - set fill pattern to a speckled pattern 
speckled (picture) 

ARGUMENT 
picture : a picture description 

USE 

Sets the fill pattern to a ‘speckled’ pattern. 

Example — 
speckled (filibox(0,0,46,180) ) 


describes 





24.45 stripesthin - set fill pattern to vertical thin stripes 
stripesthin (picture) 

ARGUMENT 
picture : a picture description 

USE 

Sets the fill pattern to vertical thin stripes. 

Example 


stripesthinr (fillbox(C,0,46,168C) ) 


describes 


279 


24 : Graphic Description Language 


24.46 stripesthick - set fill pattern to vertical thick stripes 
stripesthick (picture) 

ARGUMENT 
picture : a picture description 

USE 

Sets the fill pattern to vertical thick stripes. 

Example 
Sztipesthic. (fitibox(0,.;746,180)) 


descnbes 





24.47 waves - sets fill pattern to waves 
waves (picture) 
ARGUMENT 
picture : a picture description 
USE . 
Sets the fill pattern to waves. 
Example 
Weves( F117 55x (0; 0,46,.222)) 


describes 
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24.48 white -set fill pattern to white 

white (picture) 
ARGUMENT 

picture : a picture description 
USE 


Sets the fill pattern to white. Placing a white filled picture over an existing picture will obscure the 
picture underneath. 


Example 
white (filibox (0,0, 46,180) ) 


describes 


24.49 alpha - set fill pattern to alpha 
alpha (picture) 
ARGUMENT 
picture ; a picture descnption 
USE 
Sets the fill pattern to alpha. 
Example 
alpha (fillbox(0,0,4€,180)) 


describes 
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24.50 beta -set fill pattern to beta 
beta (picture) 
ARGUMENT 
picture : a picture description 
USE 
Sets the fill pattern to beta. 
Example 
beta (fillbox(C,0,46,180) } 


describes 


. ' 


t.o .¢ 0 © e 0&0 
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24.51 fillpattern - set fill pattern to user defined pattern 


fillpattern (pattern, picture) 


ARGUMENTS 
pettern : atom representing pattern 
picture : a picture description 
LSE 


Sets the pen pattern to the nominated pattern. The pattern is specified by an atom which consists of 
16 hexadecimal characters, as described earlier. 


For example 
greypen (fillpattern ('024508208004', fillbox(0,0,46,189))) 
describes: 
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24.52 invert - invert a picture 

invert (picture) 
ARGUMENTS 

picture : a picture description 
USE 


Inverts any filled picture within the scope of the invert operator. All the black pixels become 
white and all the white pixels become black. 


The following inverted resource picture is described by 


invert (p16 > sre (250) 307,205,455, 26 sour oe" =15900)):) 





and crosses(f{invert (greypen (dour e ( Gan 
toiek (si ibex yopo ly era. 


describes 





ipvert (thick (2222 box (GC, oraraa 





it is the filled box that has been inverted (the black pen becomes white, not transparent). Finally, 
we invert both the filled box and the filled oval. 


invert ( [crosses ([greypen (dousle(fillcvai(20,0,60,60)?}?), 
thick (fi11box (0,0, 30,40) IIN) 


HEH 
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24.53 User Defined Graphical Forms 

One very powerful feature of the MacPROLOG graphics package is the ability of programmers to 
define their own graphical forms. 

These can be new picture descriptors, new transformation descriptors, text displaying descriptors 


etc. A user defined form is then treated on an equal basis with existing system forms, enabling 
users to extend the Graphic Description Language. 


These user defined graphics descriptors, like system descriptors, are names of programs that will 
be called by the MacPROLOG graphics evaluator when it is drawing a picture described by some 
picture term. These programs have a special format, and cannot be called directly. 

In order to define a new graphic k-argument descriptor c£, simply define gf as a k+1 argument 
relation, where the last argument is a variable which q£ will instantiate to a GDL description. 


When MacPROLOG is drawing a picture and it encounters the descriptor gf with arguments 
Arg3,-.-,Arg, it will simply execute the call 


Gi(Arg,,..-,4rg,, Description) 
and then conunue the drawing operation using the Description which gf has returned. 
Note that Description can contain other user defined forms, including other uses of gf. This 
allows recursively defined user forms. But be very careful when defining recursive forms to 


ensure termination. 


For example, a star, defined as a sequence of crossing lines, whose position is specified relative to 
a point could be implemented by the program 


trans star(Y,X,trans(Y,X,lines (i (250,150), (225,180), 
(175,105) 5- (17574 SS) [223120] 12s 


In this case 

Pines (((250;.250); (225;:1860) > (175,205) + (1757195) 44225; 229)1) 
describes the star, on which < rans has the effect of translating through Y, X. 
The GDL term 

trans star (20,50) 


describes this star translated 20 pixels down and 50 pixels across. 


284 


24 : Graphic Description Language 


An example of a recursive user-form is 


movable box (DY, DX, 0,box (DY, DX, 40, 30) ). 

movable box (DY,DX,N, [box (DY, DX, 40,30),trans (DY, DX, Desc) J) :- 
0< N, 
Nl is N--l, 
movable box (DY,DX,N1,Desc). 


Below are some examples of using this user form with different initial arguments. 


add pic(movable_box(20,20,7)) 


Default Graphic Window E 


3 
| $ 
| = 

add pic(movable_bex(5,10,14). 
Default Graphic Window i 

3 

3 

ý 
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The combination of user defined forms and text provides a powerful basis for presenting structured 
information and pictures. Consider the following rather complex definition 


mytext (Num, Boxl, Text,Desc) :- 

inset_box(Boxi, (0,-20),Temp), 

offset_box (Temp, (20,0),box(T1,L1,D1,Wi)), 

inset _box(box(T1,L1,D1,Wi), (-1,-1),Border), 

inset_box(Box1, (-30,-60) , Expanded), 

offset_box (Expanded, (10,10),box(T2,L2,D2,W2)), 

++(20,T2,TextT), 

++(40,L2,TextL), 

text _width('mytext no.', 'Chicago',12,0,Width), 

++ (Width, TextL,NextL), 

pname (Num, Con), 

Desc={thick (greypen (Expanded) ),Border,textbox('’Times',12,2 
tly ble DlyWiy td; Text); toon (12.b2,;32,32,Num) ,;-ctext.(* Chicago” ,12;9 
,TeXtT, TextL, ‘mytext no.'),text('Chicago',12,4,TextT,NextL, Con) ]. 


The picture descnbed by the term 


mytext (1001, 50x(10,10;4.;, 60); "some text’) is shown below 





4c mytext no. 1001 
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inset _box and offset_box are primitives that manipulate box terms, and text_wicts 
calculates the width of a given atom. (See the chapter on Tool Building). 


A more efficient way of implementing the above user defined form would be to do less 
manipulation of arguments within the program that defines the form. This is because as the above 
definition stands, MacPROLOG would have recalculate al] the relative positions of the sub-pictures 
in the user defined form every ume one of these pictures was drawn. Given that most pictures are 
fairly static once defined, this is unnecessary. By calculating the relative positions once. oz 
creation of the new picture, we can eliminate these repeated recalculations. We could either pass 17 
all these precaiculated arguments explicitly, or save them as properties or clauses and access them 
from within the user defined form , e.g. 


mytext2 (index, Desc) :- 

picture info (Index, Expanced, Border, Text, Num, Con, 
T1,L1,D1,W1, T2,L2, TextT, TextL, NextL), 

Desc=([thick (greypen (Expanded) ), Border, 
textbox ('Times',iz,2,T1,Li,D1,W1,1i, Text), 
icontT2, L232, 32;/Ram)a 
text ('Chicago',12,C,TextT,TextL, 'mytext no.'), 
text ('Chicago',12,4,TextT,NextL, Con) ]. 


By implementing a specialized tool that used the portable editor as described in the chapter on Tool 
Building, you could allow users to reedit the text of these user defined forms . 
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Every graphics window has an associated list of pictures. Each picture on the list has: 
1) A name, unique to that window, to identify the picture. 

2) A picture description in the GDL. 

3) A local origin represented as a point pair (Y, Z). This point pair represents the shift that | 
T o be applied to the picture description in order to draw it as currently displayed in the 


4) a selection flag (1 if the picture is currently selected, O if not). 


The primitives in this chapter enable you to add to and manipulate the associated list of pictures icr 
a graphic window. 


25 : Picture Manipulation 


25.1 add pic -add a new picture to a graphic window and draw it 


add pic (desc) 

add pic (name, desc) 

add pic (window, name, desc) 

add pic (window, name, desc, org) 


ARGUMENTS 

desc : a picture description in GDL 

name : atom, name of picture element 

window : atom, name of graphic window 

org : a point pair of the form (Y, X}, amount of initial translation 
USES 


The picture described by desc is immediately drawn in the drawing area of the window. If the 
window's viewing pane 1s over that part of the drawing area, the picture immediately becomes 
visible, and it will be drawn on top of any pictures which it overlaps. Its description is recorded in 
the picture list for the window. Initially it will not be ‘selected’. 


NOTE At any given time, only a smali part of a graphic window's drawing area is visible in the 
viewing pane. By scrolling the window, the viewing pane can be moved over the drawing area. If 
you add a picture outside the currently visible part of the drawing area, then you will have to scroll 
the viewing pane of the window to see it. 


1. One argument use: Adds the picture entity described by desc tothe Default Graphic 


Window, and generates a unique name for the picture using a gensym(picture, Name) 
call. 


2. Two argument use: Adds the named picture entity described by desc to the Default 
Graphic Window. 


3. Three or Four argument use: Adds the named picture entity described by desc to the named 
graphic window. If org is given, then the picture will also be translated by the amount given, 
otherwise its local origin will be set to (0,0). 
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An example of 1 argument use of aca_pic 


Default Output Window 
- add_pic({check(fillbox(10, 20, 30, 40)), oval(50, 60, 70, 80), 
Atext(‘Helvetica’, 12, O, 140, 10, ‘An exemple of 1 argument use of 
add_pic’)}) 

YES 











E 


4 


As another example, the following picture is drawn dy the call 
draw_a_ head('a graphics windcw' 


where 'a graphics window' has previously Deen created by a call to wgcreate (see the 
chapter on Graphic Windows). 


a graphics window == 


create a graphics window 


draw_a_head(Window}:- 
add_pic(Window, head. 
fpensize(3,Z.circle(0.0.12)).box(-4.-4.4.4.10,10) .box(-4, 4, 
4.4.10,10)., lines([ (0,1). (3; 3) -03.9)..(3-3);,(0.1)]), tines ({ (6 
,-4). (8.-2), (8.2). (6.4). (6.-4)}) 1). 
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25.2 add qpic -add a new picture in Quickdraw format 


add gqpic(desc) 

add qpic (name, desc) 

add qpic (window, name, desc) 

add _qpic (window, name, desc, org) 


ARGUMENTS 

desc : a picture description in GDL 

name : atom, name of picture element 

window : atom, name of graphic window 

org | : a point pair of the form (Y, X), amount of initial translation 
USES 


The use of add_qvic is identical to that of add_pic except that the picture described by desc is 
converted to Quickdraw format first. The advantage of this is that subsequent redrawing of the 
picture (during screen refreshes and scrolling, for example), is much quicker. However, the 
disadvantage is that any ‘structure’ the picture may have had is lost - the Quickdraw picture may 
only be manipulated as a single unit. 


25.3 del_pic -remove a picture 


del pic(window, name) 


ARGUMENTS 
window : atom, name of graphic window 
name . : atom, name of picture 


USE 

The named picture is removed from the graphic window's picture list. If the picture is currently 
visible in the viewing pane, then it will disappear when the Mac next refreshes its display (see 
section on Advanced Picture Drawing). 


If there is no such picture in the window, then del_pic does nothing and the call succeeds. 
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25.4 del_sels -remove selected pictures 


del sels (window) 
ARGUMENT 


window : atom, name of graphic window 
USE 
The pictures which are currently selected in the named window are removed from the graphic 


window's picture list. If the pictures are currently visible in the viewing pane, they will disappear 
when the Mac next refreshes its display ( see section on Advanced Picture Drawing). 


25.5 del_all- remove all pictures 
del_all (window) 
ARGUMENT 


window : atom, name of graphic window 
USE 


The graphic window's picture list is emptied, and the viewing pane is immediately cleared. 


25.6 del_pic_num- remove Nth picture 


del pic_num(window, position) 


ARGUMENTS 
window : atom, name of graphic window 
position : integer. position of picture on picture list 
USE 


To remove the Nth picture from the picture list of a graphic window. If position is 1, the last 
picture to be added to the list is deleted. The picture is visibly removed when the Mac next refreshes 
its display. 


If position is greater than the number of pictures in the named window, then del pic num 
does nothing and the call succeeds. 


The primitive get_al1l_pics will retum the ordered list of all the pictures in the picture list for a 
graphic window. 


To remove the most recently added picture from a window (for example in generate and test graphic 
traces), use the call 


del pic _num(window, 1). 
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25.7 get_pic- retrieve picture information 


get _pic (window, name, desc) 
get_pic (window, name, desc, org) 
get pic(window, name, desc,org, select) 


ARGUMENTS 
window : atom, name of graphic window 
name : atom, name of picture element 
desc : variable, will be bound to the picture's description 
org : variable, will be bound to a point pair of the form (Y, X) 
select : variable, will be bound to the picture's selection flag (O or 1) 
USE 


The named picture's description, origin, and selection flag are retrieved. 
EXAMPLE 


If the picture named heac had been added to the window graphic using the example add 
call given above, then the cai 


{2 
trs 


get pic(graphic, head, Desc) 


will succeed, with Desc bound to 


ipensize(2,Z,circle(G,0,12)),box(-4,-4,0,0,10,10), 
box (-4,4,0, 5, oP 10), Lines ([(1,0) F; (2,3) f (09-3) f (33) Ly Dar 
lines ([(-4, 6), (-2,8), (2,8€), (4,6), (-4,6)])] 


25.8 chg_ pic -alter a picture's description and redraw it 


chg pic (window, name, newdescription) 


ARGUMENTS 
window : atom, name of graphic window 
name : atom, name of picture element 


newdescripticn  : picture description 
USE 


The named picture has its current description replaced by newdescription.. The old picture 
will be erased and the new picture displayed when the Mac next refreshes its display. 
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25.9 shift pic -translate a picture 


shift pic (window, name, amount) 


ARGUMENTS 
window : atom, name of graphic window 
name : atom, name of picture element 
amount : a point pair of the form (Y, X) 
USE 


The named picture entity's description in GDL is translated by the amount indicated, where 
amount is a term of the form 


(down, across) 
where down and across are integers. The integers may be positive, negative or zero. Tiis 
translation is achieved by manipulating the picture's iccal origin; the picture's description remains 


unaltered. The old picture is removed and the trarsiated picture cisplayed when the Mac nex: 
refreshes its display. | 


25.10 shift _pics -translate a list of pictures 


shift pics (window, names, amount) 


ARGUMENTS 
window : atom, name of graphic window 
names : list of names of pictures 
amount : a point pair of the form (Y, X) 
USE 


All the pictures whose names appear on the name 
where amcunt is aterm of the form 


t+) 


List are transiated by the amount indicates. 


(down, across 


with down and across being integers. The integers may be positive. negative or zero. This 
translation is achieved by manipulating each picture s .ocal origin: the pictures dese uons Ter. 
unaltered. The old pictures are removed and the transiated pictures displayed when the Mac nex: 
refreshes its display. 
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25.11 pic _frame - get a picture's enclosing rectangle 


pic frame (desc, frame) 


ARGUMENTS 

desc : picture description 

frame : variable, wil! be bound to a term of the form box (T, L, D, W) 
USE 


To find out the minimum rectangle that encloses a picture description. 


25.12 pic_centre - get a picture's local centre 


pic centre (desc, centre) 


ARGUMENTS 

desc : picture description 

centre : variable, will be bound to a point pair of the form (Y, X) 
USE 


To find out the local centre for a named picture. The picture's local origin will not be taken into 
account, so if the picture has been translated by a call to shift_pic, you will have to adjust the 
centre accordingly. 


This call is useful prior to scaling a picture about its own centre. 


25.13 sel pics - select a list of pictures and highlight them 


sel_ pics (window, names) 


ARGUMENTS 
window : atom, name of graphic window 
names : list of atoms, names of pictures 
USE 


The named pictures are selected, and immediately highlighted on the screen. This highlighting 1s 
done by surrounding the picture with four black marks, as shown below. 
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25.14 desel_pics - deselect a list of pictures 


desel pics (window, names) 


ARGUMENTS 
window : atom, name of graphic window 
names : list of atoms, names of pictures 
USE 


The named pictures are deselected, and any highlighting marks are removed. 


25.15 sel_all - select all the pictures in a window and highlight them 


sel_all (window) 


ARGUMENT 


window ‘ atom, name of graphic window 


USE 


To select all the pictures in the picture list of a graphic window, and display them highlighted. 


EXAMPLE 


If we apply se1_all to the examples of the bike drawn in the Default Graphic Window 
(see the initial chapter on the GDL), we obtain two different displays, one for the bike compnisec oi 
6 parts and the other for the bike comprised of one part. 
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Hini 
[] 


Default Graphic Window 











25.16 desel_ all - deselect all the pictures in a window 
desel_all (window) 
ARGUMENT 
window : atom, name of graphic window 
USE 
To deselect all the pictures in the picture list of the graphic window and display them unhighlighted. 


25.17 get_sel_pics -return the list of names of selected pictures 


get_sel_pics (window, names) 


ARGUMENTS 

window : atom, name of graphic window 

names : variable, will be bound to list of picture names 
USE 


To find out the names of all currently selected pictures within a graphic window. 
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25.18 get _desel_pics -return the list of names of deselected pictures 


get_desel_ pics (window, names) 


ARGUMENTS 

window : atom, name of graphic window 

names - variable, will be bound to list of picture names 
USE 


To find out the names of all currently non-selected pictures within a graphic window. 


25.19 get _all_pics - get list of pictures in a window 


get_all_pics (window, names) 


ARGUMENTS 
window - atom, name of graphic window 
names - variable, will become list of names of pictures 
LSE 
To get the names of all the pictures in the picture list of a graphic window. The saressimo 


will be bound to a list of atoms that are the names OT :ne pictures in the named winasis. 


The order of the names in the list corresponds to the order of the pictures in the window, with <2 


first picture in the list being the topmost picture in the window, anc the last picture in the list be:7 
the bottommost picture in the window. 
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Picture ordering 


The following three primitives reorder the picture list and then redraw the display according to the 
new picture list. Whilst this does not affect any individual picture description, it can result in a 
different display as previously hidden pictures may now be visible, and previously visible pictures 
may now be hidden or partially hidden. 


25.20 xeverse_pics -reverse the picture list of a window 
reverse pics (window) 
ARGUMENT 


window : atom, name of graphic window 
USE 
To reverse the order of the picture list for a named graphic window. Where pictures overlap, the 


bottommost pictures become the topmost, and the topmost the bottommost. The window is 
redrawn when the Mac next refreshes its display. 


25.21 bring to_front - bring pictures to the front of the picture list 


bring to front (window) 
bring to front (window, names) 


ARGUMENTS 
window | : atom, name of graphic window 
names : list of atoms, names of pictures 
USES 


1. One argument use: To bring to the front of the picture list all the currently selected pictures in € 
graphic window. These are immediately redrawn on top of any unselected pictures they mav 
overlap. 


2. Two argument use: To bring to the front of the picture list all the pictures in names. These are 
immediately drawn on top of any pictures they may overlap. 

Note that the pictures will be drawn corresponding to the order of their names on the names list, 
so that the first picture named in names will become the new topmost picture. 
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25.22 send_to_back -send pictures to the back of the picture list 


send to back (window) 
send to back (window, names) 


ARGUMENTS 
window : atom, name of graphic window 
names : list of atoms, names of pictures 
USES 


1. One argument use: To send to the back of the picture list all the currently selected pictures in the 
graphic window. This has the same effect as sending all the currently deselected pictures to the 
front of the picture list. The deselected pictures are immediately redrawn on top of any selected 
pictures they may overlap. 


2. Two argument use: To send to the back of the picture list all the pictures in names. This nas 
the same effect as sending all the pictures not in names to the front of the picture list. These 


pictures not in names are then immediately redrawn, possibly obscuring some of the named 
pictures. 
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Manipulating pictures using Edit commands 


The Edit menu of the programming environment can be used to manipulate pictures when a 
graphic window is the front window on the screen, as follows: 


Cut removes all the selected pictures from the window, and 
places them on the clipboard. 

Copy copies all the selected pictures in the window onto the 
clipboard. 

Paste copies any pictures on the clipboard into the 
window. 

Clear removes all the selected pictures from the window, 
without affecting the clipboard’s contents. 

Select all selects all the pictures in the window. 


The cut, copy, clear and paste primitives described in the chapter on Window Handling 
2iso manipulate pictures . 


The Clipboere format on the Defaults... dialogue determines the format used to represent 
pictures on the clipboard. 


There are two formats: 


+. MacPROLOG™ format is used for internal cutting and pasting. In this format, it is the text of 
the GDL descriptions that are used rather than the pictures they describe, so preserving any 


structural information. If you Cut or Copy to the clipboard using this format and you then do 
Show clipboard, you will see the text of the GDL description of the picture on the clipboard. 


~ QuickDraw is used for importing or exporting pictures to and from other applications. In this 
format, the GDL descriptions are converted into a single QuickDraw picture whose internal 
structure is unknown. This QuickDraw picture is displayed in the clipboard. 


Pasting cf an imported picture (through the scrapbook or clipboard) is always in QuickDraw 


format, but pasting of an internal MacPROLOG picture, say from one graphic window to another, 
will duplicate the MacPROLOG description, name and origin of the picture or pictures. 
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EXAMPLE 


The picture shown in the ‘Info on Picture’ dialogue below was copied to the clipboard from the 
Scrapbook, and then pasted into a graphic window named Graphic Editor. 
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cnt: METEOSAT aR 


Window: ‘Graphic Editor’ 


Name: | clipboard! | 
Frame: box(170, 239, 140, 98) 


Centre: 240,288 
Selected: L] 





Its description is the term 

picture (170,239,140, 98,clipbcara('l'")) 
where (170,239,140, 98) represents its size and position in the window, én: 
clipboard('1"') identifies it as the second picture to be pasted into a graphic window in 151s 


session. 


MacPROLOG keeps track of all these pictures untii the session is terminated, and assigns picture 
names to them as needed (clipboard in the above example). 


You can save pictures as resource items using the save_pic primitive explained in the chapter cn 
Advanced Drawing. 
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Extensions to picture descriptions 

Before adding a GDL picture description to a window, MacPROLOG calculates the size of the 
minimum rectangle that encloses the picture. The comers of this rectangle are marked whenever the 
picture is currently selected, and this rectangle is called the picture's frame. This frame is used 
frequently by the graphics system, but it takes time to compute. 

In addition to a GDL picture description, as described in the chapter on GDL, MacPROLOG allows 


two other ‘extended forms’ of picture description which do not require the enclosing rectangle to be 
computed by the system. 


(1) Suppose Desc is a GDL picture description, and box (T,L,D,W) describes the minimum 
enclosing rectangle for the picture. The term 


framed picture (box(T,L,D,W),Desc) 


can be used as an alternative description of the picture. MacPROLOG will take box (T, L, D, W) 
as the enclosing rectangle and will not bother to compute the rectangle. 


Example: 


add _pic(picturel, framed picture (box (10,20, 30,40), 
grey (filioval(10,2¢0,30,49)))) 


is a slightly faster way of adding a grey filled oval to the Default Graphic Window than 


adc pic(picturel, grey (filloval (1¢,20,30,40))). 
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(2) Suppose that name is the name of a picture which is in the associated list of pictures of the 
graphic window called window. The descriptor term 


window(name) 


can be used to draw the same picture in another window. Because MacPROLOG has already 
calculated the enclosing rectangle for the picture, it will not be recalculated. 
For example the call 


. 


add pic('Default Graphic Window',picture2, 
‘Default Graphic Window' (picturel), (60,0)) 


will result in a quick copy of the picture! picture of the Default Graphic Window being 
added as picture2 to the same window at the origin (60,0). 


Default Graphic Window 
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4 - add_pic( Default Graphic Window’, picture2, Default Graphic 
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The call 


add pic(mywindow, pictures 
‘Default Gra 
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and k 
will result in a copy of the picture piccure2 from the Default Graphic Window bein 
added tomywindow as picture3. This call assumes that there is no picture called picture 
already in mywindow (because picture names must be unique within windows). 
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These extensions are also valid for the add_pic and chg_pic primitives and in the format 
descriptors pbutton and pcheck for dialogue items. 
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A graphic window differs from a text window in that it is used to display graphical objects, such as 
lines, circles, and boxes rather than plain text, although it can also have edit and text fields, rather 
like dialogues. 


True to its multi-window environment, there can be any number of graphic windows in 
MacPROLOG™ at any time. They can be moved, dragged or tidied just like text windows, and the 
general window handling primitives wtype, wrename, whide, windows, cleanup, 
wfront, wshow, wvis and all the editing primitives also extend to graphic windows. 


A graphic window can have all the usual controls associated with it: a goaway box for hiding the 
window, a grow box for resizing it, and a zoom box for making the window fill the screen. The 


Default Graphic Window is a graphic window provided by the MacPROLOG system. 
Additional graphic windows can be created using the pnmituve wgcreate. 


Graphic windows are usually split into 2 panes by an adjustable vertical split line. On the left of this 
line is the tool pane, and on the nght is the viewing pane. 


The viewing pane is a viewport onto the potentially very large drawing area of the window. The 
window's vertical and horizontal scroll bars allow the viewing pane to be moved over the drawing 
ared. 


The tool pane is fixed, it cannot be scrolled. It contains the graphical images of the tools associated 
with the window, and an optional viewer. The tool images are arranged in the tool pane in vertical 
columns. The number of columns used may be set by the user. 


The viewer displays a scaled down overview of the entire drawing area. All the pictures in the 
drawing area (apart from text pictures) are shown in this overview. The current position of the 
viewing pane in the drawing area is represented by a grey outlined rectangle. This rectangle may be 
dragged to a new position, and the viewing pane will be moved to the corresponding position over 
the drawing area. Itis thus a fast alternative to using scroll bars. 


Tools are MacPROLOG programs that can be invoked to draw, get information or otherwise 
manipulate the pictures in the window. Tools have a role similar to the pull-down menu 
commands. A tool is selected by clicking on its graphical representation in the tool pane, and its 
program is then invoked by clicking in the viewing pane. The drawing area coordinates of the 
mouse click are passed to the tool's program. MacPROLOG provides a library of tool programs 
for use in your own graphic windows: these are described later in this chapter. You may also 
define your own tools: see the chapter on Tool Building. 


MacPROLOG contains two graphic windows in its programming environment. The first, the 
Default Graphic Window has been mentioned in the chapter on Picture Manipulation. The 


second, the Call-graph window, is shown below. It is used to display and interact with 


call-graphs of program relations, which assists in program development. Its use is described in the 
LPA MacPROLOG™ Environment Guide. 
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Call-graph window 


fillpoly 
ON 
= box 
Ə GET-PROP 
= On 
© EQ 
box_details = 





The tools for this window are 


Info get information on a relation node 
Graph generate a call graph for relation node 
Def find definition of relanon node 

Root find root ( first occurrence ) of user node 


A double click on any of the tools will generate a dialogue about the call graph. 
In the viewer at the bottom of the tool pane is a scaled down picture of the entire call graph. 


As with all graphic windows, by clicking and dragging on the split line you can adjust the width cf 
the tool pane. This can also be achieved by selecting Window details... from the 


Windows menu, and editing the split field numerically. This dialogue also allows you to change 
the number of tools per row in the tool pane ( i.e. the number of tool columns), switch the viewer 
on or off, and expand or shrink the maximum size of the drawing area associated with the 


Call-graph window. 


All these attributes are explained later in this chapter. 


305 


26 : Graphics Windows 


Window primitives 
26.1 wgcreate -create a graphic window 


wgcreate(window,t,1,d,w,split,maxx,maxy, vis, g0) 


ARGUMENTS 
window : atom, name of new window 
t : integer, position of top of window as number of 
pixels down from top of Mac display 
d : integer, position of left of window as number of 
pixels in from left of Mac display 
d : integer, depth of window in pixels 
wW : integer, width of window in pixels 
split : integer, width of tool area 
maxx : integer, maximum horizontal coordinate of drawing area 
maxy : integer, maximum vertical coordinate of drawing area 
vis : integer, 0 or 1 
go : integer, O or 1 
USES 


Creates a new graphic window ( a window of type grap). 
The initial position and size of the window on the screen is indicated by the t, 1, d, w parameters. 


The split determines the initial width of the tool pane, and is adjustable (using the gsplit 
primitive). | 


The maximum horizontal and vertical coordinates, maxx and maxy, determine the initial size of the 
drawing area. These can be altered (using the gmax primitive, or the Window details 
dialogue from the Windows menu). Suggested values are between 300 and 500. 


The total size of the drawing area of the window is the coordinate range 
-maxy S Y S$ maxy -maxx ££ X < Maxx. 

The initial position of the viewing pane over the drawing area is the rectangle 
(0,0,d, (w - split)) 

ie. the viewing pane initially has the point (0,0) at its top left hand comer. 


If the vis argument is 0 then the new window is initially hidden; if it is non-zero, then it is initially 
the front window, and will be made visible at the first system refresh. 


If the go flag is 1 then a goaway box is associated with the window, and if it is 0 there is no 
goaway box. 


On creation, the viewer associated with the window will not be visible, and no tools are associated 
with the window. 
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PRAGMATICS 


The t 1 d wparameters determine the size and position of the whole graphic window on the 
screen, just as with any other type of window. You can of course resize or reposition the window 
using the standard Mac mouse operations. 


It is the maxx and maxy parameters which determine the size of the window's drawing area. This 
means that you will only be able to see pictures drawn within these bounds. If you set maxx and 
maxy to be 100, say, and then draw something at (200,300), don't be surprised if it doesn't 
appear in your window! (However, if you were to subsequently extend the drawing area, using 


gmax or Window details, you could then bring the picture into view.) 


You can of course choose to use the whole coordinate plane (i.e. give a value of 32767 for maxz 
and maxy) as the drawing area, but it is unlikely that you will need all that space. The drawing area 
is how much you can ‘see’ by scrolling. If it is very large, you may have trouble ‘finding 
graphical objects that you have drawn! The viewer is also affected - because it displays a scaled 
down version of the whole drawing area, you will get more or less detail depending on the size of 
the drawing area. To start with we recommend specifying about 300 in each direction, and by 
experimentation you will find what is best for your own use. 
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26.2  gviewer - switch the viewer 


gqviewer (window, switch) 


ARGUMENTS 
window : atom, name of graphic window 
switch : atom or variable 

USES 


To set or retrieve the viewer setting for the named graphic window. 


If switch isa variable it will be instantiated to either on or off. 
If switch is one of the atoms on or off, the viewer for the graphic window is turned on or 
‘2 Bas 


Turning the viewer on allows you to see a scaled down view of the whole drawing area in the 
bottom left hand comer of the tool pane. The current location of the viewing pane is represented by 
2 grey rectangle. By dragging this rectangle it is possible to scroll the viewing pane very quickly 
over the drawing area. 
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The diagram below represents the above graphic window after dragging the dotted viewer rectangle 
up and to the left within the viewer area of the tool pane, so causing a ‘fast scroll’ of the viewing 
pane over the drawing area of the graphic window. 


A graphic window 





Note that the size of the viewer depends on the width of the tool pane. The viewer's width 1s ie 
same as that of the tool pane; its depth is then in the same proportion to the drawing area's depth zs 
its width is to the drawing area's width. : 
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26.3 gmax -the maximum size of a graphic window drawing area 


gmax (window, maxy, maxx) 


ARGUMENTS 
window : atom, name of graphic window 
maxy : integer or variable, maximum vertical coordinate 
MAXX : integer or variable, maximum horizontal coordinate 
USE 


To set or retrieve the size of tne drawing area of the named graphic window . 

On creation, a graphic window has a designated drawing area. This is the section of the QuickDraw 
coordinate plane that can be made visibie bv scrolling the viewing pane of the window. Pictures 
that lie outside of this drawing area can be added to the window, but they cannot be made visible by 
scrolling. By increasing the size of the drawing area, it is possible to bnng them into view. 


If maxy and maxx are given, then the size of the drawing area of the named graphic window is 
changed to the coordinate range 


-maxySYS maxy, -maxxS%S maxx. 


If maxy and maxx are both variables, then they are bound to the current values of the maximum Y 
and X coordinates for the drawing area. 


26.4 gsplit - get/set the split for a graphic window 


gsplit (window, split) 


ARGUMENTS 
window : atom, name of graphic window 
split : variable or integer, value of split 
USES 


To set or retrieve the value of the split (i.e. the width of the tool pane) in a graphic window. 


If split is an integer, then the tool pane width for the named graphic window is set to split, 
and the window is redrawn at the next system refresh. 


If split is a variable, then it will be bound to the current tool pane width for the named graphic 
‘window. 
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26.5  gview pane -get the viewing pane for a graphic window 


gview_ pane (window, box) 


ARGUMENTS 

window : atom, name of graphic window 

box . : variable, will be bound to a term of the form box (T, L, D, W) 
USE 


To retrieve the location of the viewing pane in the drawing area for a graphic window. 
The box argument is unified with a term of the form 


box (T, L, D, W) 


which describes the current size and position of the viewing pane rectangle over the drawing area c! 
the window. 


26.6 gscroll_to -scroll the viewing pane to a position 


gscroll to(window, top, left) 


ARGUMENTS 
window : atom, name of graphic window 
top : integer, vertical coordinate of top of viewing pane 
Tere : integer, horizontal coordinate of left of viewing pane 
USE 


To scroll the viewing pane over the drawing area such that the point (rcp, left) becomes the top 
left hand corner of the viewing pane. The scroll bars and the viewer (if it is on) are redrawn to 
reflect the new location of the viewing pane. 


26.7  gscroll_by -scroll the viewing pane by an amount 


gscroll_by (window, down, across) 


ARGUMENTS 
window : atom, name of graphic window 
down : integer, vertical shift 
across : integer, horizontal shift 

USE 


To scroll the viewing pane over the drawing area by down and across. The scroll bars and the 
viewer (if it is on) are redrawn to reflect the new location of the viewing pane. 
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Window Activation / Deactivation 


A window is activated when it is made the front window by a mouse click or through a program 


call to wfront. A window is deactivated when it was the front window, but another window 
or dialogue is activated. 


Associated with every graphic window is an optional MacPROLOG program that is called every 
time that window is activated or deactivated. This is referred to as the actdeact program. (This 
program is associated with the window internally, so even if the window is renamed, the program 
remains associated with that window.) 


26.8 gactdeact - activation/ deactivation program 


gactdeact (window, program) 


ARGUMENTS 
window : atom, name of graphic window 
program : variable or atom, name of program 
USES 


To set or retrieve the program associated with a graphic window's activation and deactivation (see 
discussion below). 

If program is given, then the actdeact program for the named graphic window is set to be that 
program. 


If program is a variable, then it will be instantiated to the name of the actdeact program for the 
named graphic window. 


The actdeact program must have two clauses. The first clause deals with activation, and the head 
must be of the form 


program(activate, Window) 
where Window is a variable which at the time of the call to program will hold the name of the 
window being activated. 
The second clause deals with deactivation and the head must be of the form 

program (deactivate, Window) 
Again, Windowis a variable which will hold the name of the window being deactivated. 
The reason that we use a variable as a second argument to hold the name of the window is that 
although a graphic window can have only one actdeact program associated with it, this program can 
be associated with more than one graphic window. 
WARNING Care must be taken to ensure that the actdeact program does not itself 


activate or deactivate any other window (for example by generating a dialogue), as 
this may cause endless recursion. 


312 


26 : Graphics Windows 


Example 
Given a graphic window called mywindow, we can have the following call to set up an activation / 
deactivation program called managemenu, 


gactdeact (mywindow, managemenu) 
where managemenu is defined by 


managemenu (activate, Window) :- 
install _menu('Margin', ['10','22','30', '40', '50']), 
get prop (Window, 'MARGIN', Last“arg-n), 
mark item('Margin',LastMargin) . 


managemenu (deactivate, Windcw) :- 
kill menu('Mazgin'). 


The result of this program is that every time the wincow zywindow Is made active, 2 menu nami 


Margin is installed in the menu bar, and when this wincow is deactivated, the menu disappeu:. 
When the menu is installed it looks for some property ‘which will have been set up erevious ly 
see which item should initially be marked. 
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26. 9 Standard Tools 


MacPROLOG provides a library of standard tool programs that can be used to select, drag, edit or 
remove any picture in a window. We recommend that you start by just using these standard tools 
in graphic windows before developing your own tools. 


The tool names given below are the names of the MacPROLOG programs which perform the 
function of each tool. You may define tools using these names and the predefined programs will 
automatically be called for those tools. However, the GDL descriptions (representing the graphical 
appearance of the tools on the screen) are fairly arbitrary and you may replace them with your own 
picture descriptions if you wish without affecting the behaviour of the tool. 


The graphical descriptions given below are predefined MacPROLOG picture descriptions which 
take no arguments. They can be used as elementary picture descriptors in any GDL description. 


n i B £ 


arrow in icon rubber cragger diamond 


The standard tools and their recommended GDL descriptions are as follows. 


26.9.1 NAME: select 
GDL DESCRIPTION: arrow () 


Allows the user to select one or more pictures by either 


a) clicking or shift-clicking over a picture. Clicking makes the picture the only selected picture. 
Shift clicking adds the picture to the number of selected pictures. To successfully click on a 
picture, you must click inside what the Mac regards as the picture's interior. In the case of 
aggregate pictures with overlapping boundaries this might not be what you expect. If you find you 
can't select the picture by clicking you can always drag a marqui. 


b) drageing a rectangle (marqui) in the viewing pane. All pictures completely enclosed by the 
marqui become selected. 


26.9.2 NAME: drag 
GDL DESCRIPTION: dragger () 


Allows the user to drag al] the currently selected pictures by clicking the mouse over one of these 
pictures and dragging the mouse. 

By clicking the mouse over any non-selected picture without any key pressed, the user can deselect 
all previous selections, and select and drag this new picture. 

If the Shift key is held down whilst clicking on a picture, this toggles the selection of the picture, 
and the user may drag all the pictures now selected. 

If the Option key is held down, then only the picture clicked on is dragged, BUT this does not 
affect the selected list. 

If the Command key is held down then the click will deselect all the pictures. 
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26.9.3 NAME: pic_info 
GDL DESCRIPTION: info_icon{() 


Allows the user to get information about a picture by clicking on it. It generates an editable 
modeless dialogue containing the picture's description, current origin, name, and a scaled version 
of the picture's graphical image. The picture can be changed by editing its description. It can be 
shifted by editing its origin or renamed by editing its name. It can also be removed from the 
window by selecting the delete button of the dialogue. An example of this dialogue is displayed 
at the end of the chapter on Picture Manipulation. | 


26.9.4 NAME: enter text | 
GDL DESCRIPTION: text ('Courier',12,0,28,10, 'A") 


Allows the user to enter text interactively into an edit field in one of two ways. 


a) By clicking and immediately releasing the mouse in the viewing pane. The user sets up an 
expanding editable line of text, into which all subsequent keyboard input will be directed unul a 
click occurs outside this line of text. 


b) By dragging a marqui in the viewing pane. The user sets up a ‘fixed size’ edit rectangle into 
which all subsequent keyboard input will be directed until a click occurs outside this rectangle. 


In both cases the active edit field created in the graphic window behaves in the same way as one in 
a dialogue, but with the extra ability to switch fonts, font style, and font size. 


A click outside the active edit field, but still inside the graphic window, will deactivate and close the 
edit field. At this point the system takes the text from the edit field and converts the information 
into a GDL description using either the text or text 50x picture descriptors. It then generates a 
name for this new picture and adds it to the window's picture list. 


The enter text tool also allows these pictures of text to be re-edited by selecting the tool and 


clicking in one of these pictures. This opens an editable line or box of text (depending on whetner 
itis text or textbox), and initialises the edit field with the text associated with the picture. 


26.9.5 NAME: eraser 
GDL DESCRIPTION: rubber () 


When the eraser tool is selected, a click over a picture will delete the picture from the window. 


NOTES 
i) A double click on any of the above tools will generate an ‘About Tool’ dialogue. 


ii) See the add_tools primitive below for how to add these tools to a graphic window. 
iii) See the Tool Building chapter for further details on tool programs. 
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26.10 add toolis -add tools to a graphic window 


add_tools (window, tools) 
add tools (window, tools, columns) 


ARGUMENTS 

window : atom, name of window 

tools : list of terms describing tools 

columns : integer, number of display columns for tools 
USES 


Each tool on the tools list is described by a compound term of the form 
name (description) 


where name is the name of the tool - i.e. the name of the program that will be called when the too! 
is used - and description is a GDL description of the tool's picture in the tool pane. 


1. Two argument use: Each of the tools in tools is added to the list of existing tools for the 
window. The number of tool display columns remains unaltered, and the additional tools are 
drawn starting at the next available rectangle in the tool pane. (See discussion below). 


2. Three argument use: The number of tool display columns is also given. If this has been 
changed since the last ad¢d_tools call for that window, then the set of tools is reconfigured o7 
the screen. 


The first time add tools is called, if the number of tool columns if not given it is set to 2. E 
there are too many tools to fit in the tool pane then only those that fit, or partially fit, will be drawn. 


Tool pictures must be described within a 32x32 pixel rectangle. Anything defined outside this 
rectangle will not be visible. The tool pictures are drawn in the tool pane from left to right (with 
the specified number per row), and from top to bottom. The graphics system calculates the heigh: 
and width for each displayed tool picture by dividing the width of the tool pane by the number o° 
tool columns. It then scales each tool accordingly. 


The width of the too] pane (the split) is adjustable. When the too! pane is assigned zero width. 
no tools will be visible, but they still exist. However, as the user cannot see any tools, it 15 
impossible to select any by clicking the mouse. The tool selection can still be changed by a call to 


set_tool,or through the Window details... dialogue. 


Each graphic window has associated with it a graphical description of its current cursor. This 
cursor is displayed whenever the mouse is in the drawing pane of the window. Individual toois 
can modify the appearance of the cursor using the gcurssr primitive. 

For example, a tool that creates a new picture object through some interactive process like dragging 
a marqui or a rubber band might change the appearance of the current cursor to a pen, whereas 2 
text-based tool, like enter text, might change it to the I-beam. The standard tools above 
change the cursor in this way. 
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Example 


The following graphic window with 2 tools is created by a call to the create_gwin program. 


create a graphics window 


create _gwin:- 


wocreate('a graphics window' ,50,50.150,250.64,300,300.1.,1). 
add_tools('a graphics window', 


[select(arrow()). pic_info(text('Times’,.12.0.28.10,'I'))], 2). 





== a graphics window > 





eree ot 





In this example, the select tool is represented by the predefined picture azrrow(}. onc 
pic info is represented by the letter I. 
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26.11 del_tools -remove tools from a graphic window 


del tools (window) 
del_ tools (window, toolnames) 
del_ tools (window, toolnames, columns) 


ARGUMENTS 
window : atom, name of window 
toolnames : list of atoms that are names of tools in the window 
columns : integer, number of columns 

USES 


1. One argument use: All the tools are removed from the named graphic window. 


2. Two argument use: The named tools are removed from the list of existing tools for the named 
graphic window. The number of columns remains unaltered, and the new, smaller, set of tools is 
reconfigured and drawn in the tool pane at the next system refresh. 


3. Three argument use: The number of tool display columns is also given. The named tools are 
removed from the list of existing tools for the graphic window, and the new, smaller, set of tools is 
reconfigured and drawn in the tool pane at the next system refresh, with the new number o! 
columns. 


26.12 get_tools -get names of tools in a graphic window 


get_ tools (window, toolnames) 


ARGUMENTS 

window : atom, name of graphic window 

tocolnames - list of atoms that are names of tools in the window 
USE 


To retrieve the list of names of the tools associated with the window. 


26.13 tool _desc - get the GDL picture description of a tool 


tool desc (window, name, desc) 


ARGUMENTS 

window : atom, name of new window 

name : atom, name of a tool in the window 

desc : variable, will be bound to the GDL description of the tool 
USE 


To retrieve the description of a named tool in a graphic window. After the call desc will be 
instantiated to the term describing the named tool. 
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26.14 gcols - the number of columns of the tool pane 


gcols (window, cols) 


ARGUMENTS 
window : atom, name of graphic window 
cols : integer or variable 

USES 


To set or retrieve the number of columns in the tool pane of the named graphic window . 


If cols isan integer, then the number of tool display columns is set to cols. The tool pane is 
reconfigured, and the tools redrawn at the next system refresh. 


If cols is a variable, then it will be bound to the current number of tool display columns. 


26.15 get_tool - get the current tool 


get_tool (window, tool) 


ARGUMENTS 

window : atom, name of graphic window 

tool : variable, will be bound to name of current tool 
USES 


To <a the name of the currently selected tool in the graphic window. If there are no tools in the 


26.16 set_tool - set the current tool 


set_tool (window, tool) 


ARGUMENTS 
window : atom, name of graphic window 
toai : atom, name of tool 

USES 


To set the currently selected tool in the named graphic window . 
If tool is the name of a tool, then the current tool is set to this tool. The tool pane is updated to 


reflect this change: the old tool is deselected and the new tool selected. Where the old tool and new 
tool are different, any activation/ deactivation programs associated with the tools will be invoked. 
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In this chapter we consider the mechanics of when and how the Mac refreshes a graphic window. 
This will introduce the concepts of transient pictures, ‘fast’ drawing, invalidation, validation and 
refreshing. 


We will also look at how resources can be used inside the MacPROLOG graphics system. 


Refreshing a Graphic Window 
There are two ways in which the viewing pane of a graphic window gets updated. 


It is updated when a picture is drawn in the viewing pane, say by an add_pic call. Drawing ina 
window results in an immediate update of the viewing pane of the window. 


It is also updated when the Macintosh refreshes its display, and certain areas of the viewing pane 
have been invalidated. An area of screen can be invalidated when it no longer correctly reflects the 
logical structure of that part of the screen. For example del_pic invalidates the area of the 
viewing pane that was occupied by the removed picture. However, the redrawing takes place only 
when the MacPROLOG system next relinquishes control to the Macintosh system, for example at 
the end of an evaluation or when a modeless dialogue is displayed. This is why del _pic does not 
immediately result in a redrawing of the viewing pane. 


Certain activities automatically invalidate parts of the viewing pane. When a window is made 
visible, resized or zoomed, then all of the window will be invalidated. But covering and uncovenng 
with another window will invalidate only those parts that were covered but are now visible. 


When parts of a graphic window's viewing pane need to be refreshed, the list of picture 
descriptions recorded for that window is accessed and used to redraw the viewing pane. 
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What add pic does 


add pic does two things. Firstly, if the picture lies in the viewing pane of the window, it 
immediately draws the picture in the viewing pane. Secondly, it records the fact that the picture has 
been drawn in the window by adding it to the picture list for the window. 


But add_pic might have done something different. 


It could have added the picture to the picture list tor the window and instead of immediately 
drawing the picture in the viewing pane, it could have simply invalidated the area of the viewirz 
pane that the picture would have occupied. The picture would then be drawn when the Macintos: 
next refreshed the screen. 


Alternatively, it could have just added the picture to the picture list for the window. The picture — 
would then appear only when the viewing pane was 7ext invalidated, for example by resizing c7 
zooming the window, but not before. 


In either case, the long term effect is the same, i.e. anew permanent picture is associated with th2 
window. The picture is permanent in the sense that wrenever the window is refreshed, the picture 
is redrawn if it lies within the viewing pane of the wincow. 


There is one other thing that add_pic might do. It could just draw the picture and not add :: 
description to the picture list for the window. The effect of this would be to make the picture = 
transient picture of the window, meaning that the next “me the window is refreshed the picture w:.. 
probably disappear because the redraw program does zot ‘know’ about the picture. 


iyt 


There is a role for transient pictures. Tools for building pictures may need to draw transies:: 
pictures: for example a tool for constructing an objec: 2s a series of closed lines. Only at the enc =: 
the tool program is it appropriate to record the desc-ction of the drawn picture in the windo% +- 
picture list to make the picture permanent. 


Tools that generate dynamic and fast moving imzsges also need to draw transient pictures. <<: 
example an “Eight Queens’ program. Only the finai s:2:e of the picture need be recorded, when <.. 
the changes have been made. 


The primitives in this chapter allow the programmer :o 


a) immediately draw a picture in a window without uncating the window's list of pictures 

b) ensure the refreshing of certain parts of a window 2: the next system refresh, by invalidation. 
c) inhibit the refreshing of certain parts of a window zt the next system refresh, by validation. 
d) force an immediate refresh of all invalidated areas of a window 

e) update the window's list of pictures without causing a redraw 
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Explicit drawing 


27.1 draw pic -draw a transient picture 


draw_pic (desc) 
draw_pic(window, desc) 
draw_pic(window, desc,org) 


ARGUMENTS 
window : atom, name of graphic window 
desc : a ( possibly extended ) picture description in GDL 
org : a point pair (Y, X) , the local origin 

USE 


To immediately or 'fast' draw a transient picture in a graphic window without recording the picture 
in the window's picture List. 


1. Three argument use 
Fast draw the description in the named graphic window, using the given local origin. 


2. Two argument use 
Fast draw the picture in the named graphic window, with a local origin of (0,0). 


3. One argument use 
Fast draw the description in the Default Graphic Window with a local origin of (0,0). 


In a graphical version of the “Eight Queens” problem, a queen can be visually removed from a 
Square by a call of the form 


draw pic (board, blankbox, whitepen (white (filibox(D,A,32,32))) 
where D and A identify the chessboard square. 


NOTE 
draw pic does not update the window's picture list. If you want the drawn picture to be a 
permanent picture of the window, i.e. to be redrawn when the window is refreshed, you should 
either use add_pic, or, in addition to the draw_pic call do an explicit record_pic on the 
window. Use draw_pic for fast updating of dynamic pictures that will change several times 
during a given query “(such as a graphic trace of a program solving the "Eight Queens" problem or 
“Tower of Hanoi"). Just before the query terminates you can record the final state of the picture 
using record pic to update the picture list for the window. 
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Invalidation 
Invalidation is used in connection with explicit drawing. 


Suppose that you have drawn some transient pictures in a window on top of some permanent 
pictures. You now wish to remove the transient pictures and make the permanent pictures 
underneath visible again. For this you would use invalidation. 


Minimally, you need to invalidate the areas occupied by the transient pictures. The next time the 
Mac refreshes its display, the permanent pictures will reappear. If you want the permanent pictures 
to immediately reappear, you need to invalidate the relevant areas and force a refresh of the display 
using the refresh_now primitive (see below). This refreshes all the currently invalidated areas 


of the window and sets them back to valid. 


You can invalidate the whole of the viewing pane of a graphic window, or just part of it. For 
faster refreshing it is best to invalidate the smallest area that encloses the picture to be redrawn. 
This area is referred to as the picture's frame, and is calculated and recorded by the system when z 
picture's description is first added to a window's picture list. 


del pic, shift_picandedit_pic all use invalidation to make the parts of the screen 
underneath the moved or removed picture be redrawn. They also invalidate the viewer if it :s 
present. The effect of using these primitives is therefore only visible at the next system refresh. 


Validation 


Validation is the converse of invalidation. It causes the Macintosh to remove invalidated areas fror. 
its records, and this will prevent a redraw of those paris of a window. This can be useful to ensure 
that certain parts of the screen image are not redrawn at the next system refresh. 


Validating the Viewer 


A call to refresh_now will also redraw the viewer for the window, which can be quite a time 
consuming operation. If you are making several changes to a window by shifting or editing 
pictures and you want to repeatedly call refresh_now to make the changes immediately visible. 
it is better to delay the updating of the viewer until the end of the sequence of changes. The refresh 
of the viewer can be inhibited by validating it before the call to refresh_now (see the 
val viewer primitive). At the end of the sequence of changes you could then call 
refresh _z=ow without validating the viewer, so that it too will be updated to reflect the final state 
of the window. 
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27.2 ainval_pic -invalidate the 'frame' of a picture 


inval pic (window, desc) 
inval pic(window, desc, org) 


ARGUMENTS 
window : an atom, name of graphic window 
desc : a (possibly extended ) picture description, as in draw_pic 
org | : a point pair (Y, X), the local origin 

USE 


To invalidate the rectangle that would be occupied by the described picture. This may be used for 
instance to redisplay what lies underneath a transient picture drawn by draw_pic. 
27.3 inval box -invalidate a given rectangle 


inval_box (window, box) 
inval_box (window, box, org) 


ARGUMENTS 
window : an atom, name of graphic window 
box : a term describing a rectangle 
org : a point pair (Y, X}, the local origin 
USE 


To invalidate a given rectangle. The box argument must be a term of the form 
box(T,L, D, W) 


For example, we could write a program to invalidate the viewing pane of a graphic window as 
follows. 


inval viewing pane (window) :- 


gview pane (Window, Rect), 
inval box (Window, Rect). 
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27.4 inval tool pane -invalidate the tool pane 


inval_tool_pane (window) 


ARGUMENT 


window : atom, name of graphic window 


USE 


To invalidate the tool pane of a given graphic window. If we had a tool picture whose 
representation changed depending on, say, a menu selection, then we could invalidate the tool paze 
whenever that menu was changed, thus forcing the up-to-date description of the tool to be drawn. 


Example 


In the program below, we have a tool sizetoo in the tool pane whose description is a use’ 


form, newsize, which is sensitive to a property associated with a menu $ize. The graphicc. 
representation of the tool is the number representing ‘ne currently selected text size. Therefore. 
whenever the selected menu item is changed we neec to update the tool's appearance in the :c7. 
pane by a call to inval_tool_pane. 


go:- % initialisation routine 
wgcreate (mywindow, 50,50, 200,200, 23,229,500,1,1), 
add_tools(mywindow, [sizetool (news.i2¢imywinccw))}), 
| a | 


install menu ('Size',['10','20', 
mark_item('Size','10'), 
set _prop(mywindow, 'SIZE','10'). 


er z install menu 
initially mark an item 
and set a property 


a a 


on? 


‘Size’ (Value):- 
On (Value, F810" 27207, 7 30 T Fa 
get prop (mywindow, 'SIZE', Previous , 
Previous =\= Vaiue, 
unmark item('Size',Previcus), 
mark item('Size’,Value), 
set prop(mywincow, 'SIZE', Value), 
invai_tool_pane(mywindow). 


yt 


deal with menu selection 
check its a valid size 

get previous value 

if different menu selection 
update menu marks 

mark the new selection 
update property 

redraw tool pane 


AO O AO NT AO A) 


ay? 


newsize (Window, Desc} :- user defined descriptor 
get prop (Window, 'SIZE', Size), get current size to be show 
Desc = text('Times',12,0,28,6,Siz¢2 . s return new description 


ot 


wy? 
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27.5 inval viewer - invalidate the viewer 
inval viewer (window) 
ARGUMENT 
window : atom, name of graphic window 


USE 


To invalidate the viewer for a given graphic window if itis on. If the viewer is not on, the call 
succeeds but has no visual effect. 


27.6 val_box - validate a rectangle 


val_ box (window, box) 
val_ box (window, box, org) 


ARGUMENTS 

window : an atom, name of graphic window 

box : aterm of the form box (T, L, D, W 

org : a point pair of the form (Y, X), the local origin 
USE 


To validate a given rectangle, and thus inhibit a refresh of that part of a window. 


27.7 vwal_viewer - validate the viewer 

val viewer (window) 
ARGUMENT 

window : atom, name of window 
USE 


To validate the viewer for a given graphic window, if it is on. If the viewer is not on, the call 
succeeds but has no visual effect. 
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27.8 val pic -validate the ‘frame’ of a picture 


val pic (window, desc) 
val pic (window, desc, org) 


ARGUMENTS 
window : an atom, name of graphic window 
desc : a (possibly extended ) picture description, as in draw _pic 
org : a point pair (Y, X), the local origin 

USE 


To validate the rectangle that would be occupied by the cescribed picture. 


27.9 xrefresh_now-refresha window 

refresh now (window) 
ARGUMENT 

window : an atom, name of graphic window 
USE 


To force the immediate redrawing of all the invalidated areas of a graphic window. To be usec 
when you do not want to wait for the system to refresh a window. 
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EXAMPLE 


There are numerous ways of writing a program that translates a given list of pictures. We compare 
and contrast the different graphical behaviours of three similar but different programs. 


In the program below we backtrack through a list of pictures, shifting each one, and at the end we 


force a redrawing of the window in which the pictures lie. Nothing will visibly happen before 
then. 


move pics (Window, Pics) :- 


on(Pic,Pics), % for all pictures on the list 
shift pic(Window, Pic), % shift one 
fail. % backtrack to on 


move pics (Window, Pics) :- 
refresh now(Window}. % force a redraw 


In the next program we again backtrack through the list of pictures, shifting each one, but force a 
redraw of the window after every shift. 


move pics (Window,Pics) :- 
eni{Pic, Pics); : % for all pictures on the list 


shift _pic(Window,Fic), 
refresh_now(Wincow), 
Laris 


& shift one 
© force a redraw 
% backtrack to on 


move pics (Window, Pics). 


However, if the viewer is on for the window, then the viewer will also be redrawn after each shift. 
This could be quite slow for a long picture list. We could inhibit the viewer being refreshed by a 
call to val_viewer, as below. 


move _ pics (Window, Pics) :- 


move pics (Window, Pic 
A 


òñn({FPiC; P125); 
shift_pic(Window,Pic), 
val_viewer (Window), 
refresh _now(Windcow), 
fail. 

5jise 
inval viewer (Window), 
refresh now (Window). 


% forall pictures on the list 
& shift one 

$ inhibit refresh of viewer 
& force a redraw of window 
% backtrack to on 


% force refresh of viewer 
% force a redraw . 
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27.10 record pic -add a picture toa window without displaying it 


record pic (desc) 

record pic (name, desc) 

record pic (window, name, desc) 

record pic (window, name, desc, origin) 


ARGUMENTS 
desc :a (possibly extended ) picture description in GDL 
name : an atom, name of picture to be inserted 
window : an atom, name of graphic window 
origin : point pair, amount of local shift 
USE 


To record the given picture in the picture list for a graphic window but not immediately draw ::. 
(The drawing will take place at the next system screen refresh.) 


1. One argument use 


Generates a unique name for the picture, inserts it into the Default Graphic Window. cnc 
gives it a local origin of (0,0) 


2. Two argument use 


Inserts the named picture into the Default Graphic Window, and gives it a local origin ~< £ 
(0,0) 


3. Three argument use 
Inserts the named picture into the named window, and gives it a local origin of (0,0) 


4. Four argument use 
Inserts the named picture into the named graphic wincow with the given local origin. 


NOTE A draw pic followed by a record =-< is equivalent to an add_pic. See ine 
discussion at the beginning of this chapter. 
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27.11 record qpic -add a picture in QuickDraw format without displaying it 


record qpic(desc) 
record qpic (name, desc) 

record qpic (window, name, desc) 

record qpic (window, name, desc,origin) 


ARGUMENTS 
desc :a (possibly extended ) picture description in GDL 
name : an atom, name of picture to be inserted 
window : an atom, name of graphic window 
origin : point pair, amount of local shift 
USE 


Exactly the same as record pic, except that the picture will be added as a QuickDraw picture. 


As with the corresponding add_qpic call, this speeds up subsequent redrawing of the picture, 
but you lose the picture's Prolog structure. 


27.12 remove_pic - 'silent' removal of a picture 


remove_pic(window,name) 


ARGUMENTS 
window : atom, name of a graphic window 
name ; atom, name of a picture 

USE 


This is similar to record_pic in that no immediate refreshing of the screen takes place. The 
named picture is removed from the window's list of pictures, but it will remain visible on the 
screen until the screen is next updated. 
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Using Resources 


MacPROLOG Graphics provides primitives to access resources of type "PICT", 'CURS' or 
ICONA 


Resource pictures can be accessed using the GDL picture descriptor, and saved to disk using 
save pic. 

Resource icons can be accessed using the GDL icor descriptor. 

Resource cursors can be accessed using gcursor. 


EXAMPLE 1 


The following program displays in a graphic window all the icons in currently open resource files. 
(The res_ items primitives is documented in the Resources chapter.) 


add_all_icons (Window) :- 
res items('ICON',ListOfIcons), 
add_icons (Window, ListOfIccns,0). 


x? 


get list of resource icons 
start with zero 


O 


add_icons (Window, [],N). 

add_ icons (Window, [H|Rest],N) :- 
add _one_icon(Window,H,N), 
Nl is Nel, 
adda_icons (Wincow,Rest,N1). 


a? 


work through list of icons 
add the head of the hist 
increase counter 

work through the rest 


ane 


ok! oe 


add_one_icon (Window, [RName, Rum, File.,1), 
gensym(resource_icon,Next-con), generate anew name 
NextX is N**232, move along 32 pixels 

ad sic (Window, NextIcon, icon (0, Next, 32, 32,R0um) ) . 
7 = add it to the window 


add Nth icon 


a a 


cat 


EXAMPLE 2 


The following program that finds all the available resource pictures in currently open resource fies. 
and then adds them to a graphic window. using their cnginal dimensions. 


add all pics (Wincow) :- 
res items('PICT',ListOfP-cs), z Get list of resource pictures 
on({Name,Num,Fiie],ListC=Pics), Find a picture on the list 
gensym(resource picture,NextPict., Generate a new name 
pict frame (resource (File, Num) ,box(7,L,D,W)) , % Get its dimensions 
add Dic (Window, NextPict,picture(T,_,D,W, resource (File, Num) )}), 
fail. Add it to the window and f=: 
(This backtracks to on) 
Succeed when there are no 
% more pictures 


a 
zz 
> 
a 
z 
= 


one eX? 


a? 


add_all_pics (Window). 
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27.13 save_pic - save a picture in a resource file 


Save pic(name, desc, file) 
Save pic(name, desc, file, volume) 


ARGUMENTS 
name : atom, name of resource picture 
desc >a (possibly extended ) picture description in GDL 
file : atom, name of resource file 
volume : integer, volume identifier 
USE 


To save a picture description to disk as a permanent resource picture. 


1. Three argument use The default volume is used. 


“* 





Four areument use: The picture is saved in the named file on the given volume. 
*3 le can be the name of an existing MacPROLOG program file, or it can be a new file name. 


If the file already exists and has a resource fork, then the resource fork will be opened and the 
picture saved there. 


If the file already exists but has no resource fork, then the resource fork will automatically be 
created. 
If the file does not exist, then both the file and the resource fork will automatically be created. 


Once a picture exists on disk as a resource, it can be displayed in either a graphic window or a 
dialogue very efficiently using a picture description of the form 


picture (T,L,D,W, resource (Name, File) ) 


OT 


picture (T, L, D, W, resource (Name, File, Volume) ). 
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27.14 qpic_frame -return a QuickDraw picture's dimensions 
qpic frame (pi cture details, rectangle) 
ARGUMENTS 


picture details : description of a resource picture 
rectangle : variable, will be unified with a term of the form box (T, L, D, W) 


USE 


To find out the dimensions of a QuickDraw picture. This can be useful before using the picture in 


+ 


a picture description. Getting and using the original dimensions prevents distortion of the picture. 


Examples of valid calls: 


cpic frame (clipboard('1'),Rectangle) 
apic frame (resource (Name, File) ,Recta=3-¢) 

qpic frame (resource (Name, File, Volume; ,*ectangle) 

Example 

The following program will add a QuickDraw resource picture to a graphic window in its onigiri: 
dimensions and at its original coordinates. 


add qpic (Window, Name, File):- % add a QuickDraw picture 
qpic_ frame (resource (Name,File),2ox(T,L,D,#)), % get dimensions 
gensym(qpic,PicName) , % generate a name 


add pic (Window, PicName, picture 7,1,D,W, resource (Name, File)):. 
% add it to window 


27.15 qpic size -return a QuickDraw picture's size 
qpic_size(picture_details, numberofbytes) 
ARGUMENTS 
picture details : description of resource picture 
numberofbytes : variable. will be bound to size of picture 


USE 


To find out the size of a QuickDraw picture. Useful in memory management. You may find t"2: 
larger pictures can occupy up to 12K or more of memory. 


Example uses: 


qpic size (clipboard('1l'),Numberoftbyces 


opic size (resource (Name, File),Numbercibytes) 


gpic_size (resource (Name, File, Volume) , Numberofbytes) 
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27.16 gcursor -associate a new cursor with the viewing pane 


gcursor (window, cursor) 


ARGUMENTS 
window : atom, name of graphic window 
cursor : a cursor descriptor as listed below 
USE 


To change the appearance of the current cursor associated with the viewing pane of a graphic 
window. 


A cursor descriptor is a term with one of the following forms 
a) resource (num, fiie, vol) 
b) resource (num, file) 
c) resource (num) for a currently open resource file 


d) user (hex_atom) 
where hex atom is an atom comprised of 128 hexadecimal characters 


e) one of the following reserved cursor names which denote the displayed cursors 


Q Ll Z 


spy glass i_beam pen 


t cP eo O Il 


cross hair thick_cross watch garbage split 


S & b Gp R 


left_thumb right_thumb down_thumb up_thumb arrow 
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In the chapter on Graphic Windows we described some standard tools that can be used in graphic 
windows. In this chapter we show how you can buiid your own specialized tools. We descnbe 
the required format of tool programs and a number of primitives which can be used to help in 
implementing specialized tools. 


The format for tool programs 


Recall that a tool in a graphic window is implemented by a PROLOG program, and its picture in the 
tool palette is determined by a GDL description. The name given to the tool in the graphic window 
is also the name of the PROLOG program invoked whenever the user clicks in the relevant parts c! 
the window. 


In fact there are a number of circumstances in which a tool program is invoked: when the tool is 
first selected from the tool palette, when the user clicks in the viewing pane, and when the tool :s 
deselected (before another tool is selected from the :col palette). The forms of these invocations 
are: | a 


Form of call Tosser for call 
l. toollactivate, Window) tool is selected 
2. tool({Window, Y, X, Mod) mouse click in drawing pane 
L tool (deactivate, Window) tooi is ceselected 
4, tool (double, Window) doutie click occurs on the tool picture 
5. tocl(close_ec:it, Window) too! =as opened an edit field which has beer 


closed by a click outside the field 


1. A tool is selected by the user clicking on the picture representing it in the tool palette. [: 
becomes the currently selected tool, and is activated. The activate mode of the tool is invoked, Tz 
format of this cali is 


tool(activate, Window) 
where ac- vate is an atom which denotes the activate mode, and ‘Vindow will be the name c’ 
the graphic window containing the tool. The funct:on of the activate mode is to allow the too: :o 
perform any initialisations prior to it being invoked. 


A common function for an activation mode is to change the current cursor using the gcurs=-= 
primitive. 
For example: 


mytool (activate, Window) :- 
gcursor (Window,pen). 


will cause the cursor to be switched to a pen when mytool is activated. This cursor will be 
displayed whenever the mouse is moved into the viewing pane of the graphics window. Changins 
the cursor can give the user a visual indication of the nature of the tool to be invoked. 
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2. When the mouse is clicked in the viewing pane, MacPROLOG invokes the currently selected 
tool program with the details of the mouse click as parameters. This is the click mode of the tool, 
usually the most important mode. The format for this call is 


tool (Window, Y, X, Mod) 


where Y and X are the down and across coordinates of the mouse click in the drawing area of 
Window, and Mod is an integer indicating the keyboard status at the time of the click, i.e. whether 
or not any of the ‘modifier’ keys such as Shift or Option were down when the mouse click 
occurred. The Mod value can be: 


0 Nokey down 
256 Command kev down 
512 Shift key down 
1024 Caps Lock key down 
2048 Option key down 


This information is important for some tools where the state of the modifier keys affects the 
behaviour of the tools. For example, traditionally, a shift-click extends a selection, whereas a click 
without any modifiers selects a new object. 


3. The third mode is the deactivate mode. This is invoked when a tool is deselected, 1.e. 1t was 
active, but another tool has now been selected. The format for this deactivate call is 


tool (deactivate, Window) 


where deactivate is an atom which denotes the deactivate mode, and Window is the name of 
the graphics window containing the tool. Example: 


mytool (deactivate, Window) :- 
gcursor (Window,cross hair). 


This deactivate mode allows the programmer to 'tidy up’ after using a tool. 


4. The fourth mode is the double mode. This is invoked when the user double-clicks on a tool. 
The format for this call is 


tool (double, Window) 


where double is an atom which denotes the double mode, and Window is the name of the 
graphics window containing the tool. 

For example, one might give the user help about a tool if they double click on the tool. This could 
be done by having a help file ( see the help primitive) called ‘Application Help’ (say) and a tool 
clause of the form: 


mytool (double, Window) :- 
help('Application Help',tool3,''). 


5. The fifth mode is the close_edit mode. This use for edit fields 1s explained in more detail 
below. 


Note 

The activate, deactivate, double andclose edit modes of a tool program are 
optional - the call can immediately fail due to the absence of a matching clause. However, a tool 
program must have a ‘click’ mode defined (mode 2 above). 
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Tool Building Primitives 
28.1 marqui - interactively draw a marqui 


marqui (window, pivot, marquirect) 


ARGUMENTS 
window : atom, name of graphic window 
pivot : point pair of the form (Y, X), fixed point of marqui 
marquirect : variable, will become the rectangle drawn 

USE 


marqui enables the user to drag a marqui, which is a grey hollow rectangle that follows the mouse 
while its button is being held down, with one comer fixed at pivot . Typically this is where the 
mouse was clicked in the viewing pane. When the mouse button is released, the rectangle that "2s 
been drawn is returned as the value of marguirecz, which will be a term of the form 


box(T, dss D, W) 


The marcu i call will fail if the mouse does not move at all (i.e. if the user simply clicks anc 
releases the mouse in the same place). 


Example use 


You may often use marqui in the ‘click mode’ program of a tool, passing in the coordinates of the 
mouse click to marqui. Below is a tool, which we might call add_filled_ova `, that enabies 
the user to interactively add a grey filled oval. 


add filled oval (Win, Y,X,Mod) :- 
marqui (Win, (Y,X),box(T,L,2,W)), 
gensym(filledoval,Name), 
add pic(Win,Name, grey (filioval(T,-,9,W))). 


get the marqui rectangle 
generate a name 
add a grey filled oval 


AP oF ot? 


Note the use of gensym to create a new unique name for the picture element about to be added. 
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28.2 find pic - find the uppermost picture under the mouse 


find pic (window, point, name) 
find pic (window, point, name, desc, org) 


ARGUMENTS 
window : atom, name of graphics window 
point : point pair of the form (Y, X), position of mouse 
name : variable, will be bound to the topmost picture under point 
desc : variable, becomes description of picture found 
org : variable, becomes origin of picture found 
USE 


Given a mouse position as a point pair, find _pic will return the name of the uppermost picture 
found underneath the mouse position, and optionally its description and ongin. 


For example, a tool called eraser that deletes a mouse selected picture from a graphics window, | 
and clears it from the screen on the next system refresh, might have its click mode defined as 
follows. 

eraser (Window, Y,X,Mod):- 


find pic (Window, (Y,X),Name), 
del pic (Window, Name). 


28.3 replace pic -find and replace the picture under the mouse 


replace pic (window, point, name, desc, newdesc) 


ARGUMENTS 


window : atom, name of graphics window 

point : point pair of the form (Y, X) , position of mouse 

name - variable, will be bound to name of picture underneath pt 
desc : variable, will be bound to old picture description 
newdesc : new picture description 


USE 


This is a ‘find and replace’ usage which is more efficient than accessing the picture twice, say with 
find pic andthen chg_pic. Given a mouse position as a point pair, replace_pic will 


return the uppermost picture found underneath the cursor position. The picture will be redrawn 
using newdesc, and its description in the picture list will be replaced as well. 


m 
A tool that scales a mouse selected picture about (0,0) by a factor of 2 in both directions could be 
defined by 


scaler (Win, Y,X,Mod):- 
replace pic(Win, (Y,X),Pic,Desc, scale (2,2,bDesc)). 
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28.4 find pics - find the list of pictures under the mouse 


find pics (window, point, names) 


ARGUMENTS 
window : atom, name of graphics window 
point : point pair of the form ! Y, X), position of mouse 
names : variable, will be bound to list of picture names 
USE 


Given a mouse position as a point pair, #ind_pics will return the list of all the pictures foun 
underneath this mouse position, where the first in the List i is the uppermost of the pictures, and i: 
last the bottommost. 


For example, a tool that makes the bottom picture uncer tne mouse the top picture micnt be defines 
as 


ring to_top (Window, Y,%, Moai :- 
find _pics (Window, (Y, X), Pics}, 


ger last (Pics,Name), z get last name on Pics 
pring to front (Window, Wame]). 


where get_ lest is some program defined to return the last element of a list. 


28.5 pics _in_box - find the list of pictures in a rectangle 


pics in_box (window, rectang-e, names) 


ARGUMENTS 

window : atom, name of graphics window 

rectangle : term of the Hm -s Th E PED 

nares : variable, will be bound to list of picture names 
USE 


Given a rectangle, pics_in_box will retum the list of all those pictures that lie compietely insic: 
that rectangle. “This primitive looks at a picture's frame to see if it lies in the rectangie. 
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28.6 pt_in pic -see ifa point is in a picture 


pt_in pic(window, point, name) 


ARGUMENTS 
window : atom, name of graphics window 
point : point pair of the form (Y, X) 
name : atom, name of picture 

USE 


Given a point and a picture name, pt_in_pic succeeds if the point is in the picture, and fails 
otherwise. The call succeeds if the point is actually in the picture’s interior, and not just inside its 
frame. In the case of overlapping aggregate pictures, and polygons with crossing lines, this 
interior may be a lot smaller than you'd expect 


28.7 rubber band - drag a rubber band 


rubber band (window, pointl, point2) 


ARGUMENTS 
window : atom, name of graphics window 
point] : point pair of the form (Y, X), initial point 
point2 : vanable, will be bound to a point pair, final point 
USE 


Given an initial point in the viewing pane, rubber band allows the user to drag a rubber band 
(i.e. a grey dotted line) around the viewing pane. When the mouse is released, a grey dotted line is 
drawn connecting the initial point, point1, to the point where the mouse was finally released, 
pointed. 

(You may then want to call add_pic to make this last line permanent.) 
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Rubber Band Example 


A tool called add lines which allows the user to build up a set of joined lines by dragging a 
rubber-band might have its click mode defined as follows. 


add_lines (Win, Y, X, Mod) :- 
gcursor(Win,pen), % make cursor a pen 
rubber band(Win, (Y,X),Nxt), % get first line 
rubber Loop (Win, Nxt, (Nxt, (7,4) ],4--P7ts,0), % pass Q as initial Modifier 


gensym(userLines,Syname) , % get a unique name 

add _pic(Win,Syname,lines(A.2?ts)). % add joined lines picture 
rubber leoor (Win, Ptin,Ptsofar,aA:lFts, tie % while no key is pressed 

{ 

-t 

wait click (Win, Z,X,Mod),` z mouse click signals new lize 


rubber cand (Win, ?tin,Ptout), 
rubber ioop(Win, Ptout, [Proutirtsccar), AllPts,?4od). 


et ee c,e4 


rubber _iccop(Win,Last?t,Alircs 220 24) 4 % finish if non-zero od 


wait click waits for the user to press the mouse cown again inside the viewing pane, to start 
another line (for a description of wait cea sez tne section on the mouse and events below } . 
A ‘modified’ click is used to terminate the zukcer l-2cp. This is when the user clicks the mouse 
with, say, the Option key down. In this case ¢ the '‘o 2 argument will be non-zero, and the seconc 


clause for rusher loor will be used. 
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28.8 drag pics -drag a list of pictures 


drag pics (window, names, start,amount) 


ARGUMENTS 

window : atom, name of graphics window 

names : list of picture names to be dragged 

start : point pair of the form (Y, X) , initial mouse click 

amount : variable, will be bound to a point pair giving the distance of drag 
USE 


To allow the user to drag a given list of pictures around the screen. 


While the mouse button is down and within the viewing pane, a grey outline of the pictures will 
follow the mouse. This will disappear when the mouse is released. 


xample: 


¢rag_pics can be used to define the click mode of a dragger tool which allows the user to drag 
the currently selected pictures. 


dragger (Window, Y,X,512):- % if Shift key is down 
t 
=F 
select (Window, Y,X,512). % just toggle selection 
aragger (Window, Y¥, X,Mod):- 
get_sel_ pics (Window,Pics), t get currently selected pics 
drag pics (Window,Pics, (Y,%),Delta), % allow user to drag them 
shift_pics (Window, Pics,Delta). % and record translations 
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Mouse Clicks and Events. 


The Macintosh is an ‘event-driven’ system. The user drives the system by using the mouse and 
generating events that are recorded and interpreted by the underlying system. There are many types 
of events, the most important being: 


click (i.e. mouse down) 
release (i.e. mouse up) 


As events occur the Macintosh puts them in an event queue. The following MacPROLOG 
primitives allow programmers access to this event queue to find out whether or not certain events 
have or have not occurred. Most of these primitives need the name of a graphics window to be 
passed as the first argument. This must be the selected window at the ume of the call. 


28.9 wait click - wait for mouse click in viewing pane 


wait click (window, down, across,mod) 


ARGUMENTS 
window : atom, name of graphics window 
down ‘ variable. will be bound to vertical coordinate 
across : variable. will be bound to horizontal] coordinate 
mod : variable, will be bound to integer, modifier value 
USE 


wait click suspends a MacPROLOG evaluation until the user presses the mouse button down 
in the viewing pane of the window. It then returns the position of the mouse within the drawinz 
area. 

~od will have an integer value indicating the keyboard status at the time of the event. Le. whether 
or not any of the ‘modifier’ keys such as Shift or Option were down when the mouse clicx 
occurred. The mod value can be: 


0 No key down 
256 Command key down 
$12 Shift key down 
1024 Caps Lock key down 
2048 Option key down 


If the user presses the mouse button down outside the viewing pane, then a beep is sounded. 


If window is not the front window at the time of the call, wait_click fails. 
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28.10 clicked - test if there has been a mouse click in viewing pane 


clicked (window, down, across,mod) 


ARGUMENTS 
window : atom, name of graphic window 
down : variable, will be bound to vertical coordinate ~ 
across : variable, will be bound to horizontal coordinate 
mod : variable, will be bound to modifier value 

USE 


To test to see if a click has taken place in the viewing pane of the named graphic window. The cali 
fails if the user has not pressed the mouse button or if window is not the front window. A 
subsequent call to clicked will succeed only if the user has clicked again: the ‘click’ is removed 
from the event queue by this primitive. 


The clicked primitive enables tool programs to be interrupted by clicks in the viewing pane. For 
example, in a graphical trace program you might test for a click at the beginning of every new trace. 


If the user has clicked the mouse, a dialogue may be generated asking the user if they wish to stop 
the trace. 


28.11 get_mouse - get the current position of mouse in the drawing area 


get_mouse (window, down, across) 


ARGUMENTS 
window : atom, name of graphicswindow 
down : variable, will be bound to vertical coordinate 
across : variable, will be bound to horizontal coordinate 
USE 


To find the current position of the mouse in the drawing area of the named window. If the mouse is 
not in the drawing area of the window, or if window is not the front window, the call fails. 


28.12 mouse_down - test if mouse is still down 
mouse_down 
USE 


To test if the mouse button is still pressed. If the mouse button is currently down, the call 
succeeds, and fails otherwise. 
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28.13 mouse _up -test if mouse has been released 


mouse up 
mouse up (window, down, across) 


ARGUMENTS 
window : atom, name of graphics window 
down : variable, will be bound to vertical coordinate 
across : variable, will be bound to horizontal coordinate 
USE 


To see if the mouse has been released. If a 'mouse-up' event has occurred then the cail succeeds. 
In the three argument form, the call returns in the down and across arguments the position of 
where the mouse was released in the viewing pane of the graphic window. 


EXAMPLE | 


Using these primitives we outline a simple ‘picture dragger’ tool which finds the top picture under 
the mouse, and then draws a grey image of it in xoz mode on the screen, following the mouse’s 
movements. 

By using xcr mode, we can remove the previous image of the picture by redrawing itin its olc 
position before we draw its new image. 

We use fast drawing (draw pic rather than add_sic) to immediately change the screen s 
image. 

Inredraw sic we have used draw_gic ona translated description of the picture using tre 
~rans picture descriptor. Alternatively, we could have left the picture description alone. and offset 
its local ongin. 


ragger (wiindow, Y; X; 0d) :- 
mouse =own, 
find cic(Window, (Y¥,X),Name, [esc,% 


psi z get picture to crag 
follcw_mouse (Window, Y, X,renmode (xc A 


' T 
, greypen (Desc)), Org, 1, 1))}, 
set pen to xor anc grey 


get_mcuse (Windcw, Y9, X9), s get final mouse posiuon 
gap (Y¢,X9,Y,X,C0Y,DX), $ calculate amount dragged 
shift _pic(Window, Name, (DY,°X)). % record drag 

follow mouse (Window, ¥,X,Desc,Crg, Iniz) :- 
mouse up, 
ae % if released, then terminate 


follow mouse (Window, Y,X,Desc,Ozrg, Init) :- 
get mouse (Window, Y9, X9), cet new mouse position 
redraw pic (Window, Y, X, Y9, X3, Desc, Org, Init) , draw new picture position 
follow_mouse (Window, Y9,X9,Desc,Orc, init). % loop round 


ont An 
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redraw pic(Window, Y,X,Y,X,Desc, Org, Init) :- % picture hasn't moved 
? 


redraw_pic (Window, Y1,X1,Y9,X9,Desc,Org, (Y0, X0}):- 


gap (Y1,X1, Y0,X0,DY,DxX), % get old drag gap 

gap (Y9,X9, YO, X0,EY,ExX), % get new drag gap 

draw pic (Window, trans (DY,DX,Desc),Org), _% redraw at old posn. (to erase) 

draw pic (Window, trans (EY,=X,Desc),Org). $ draw at new position 
gap (YO, X0,Y9,X9,DY,DX):- 

DY is YO--Y9, % use integer subtraction 

DX is X0--X9. % use integer subtraction 
EXAMPLE 2 


We now outline the basis of a simple marqui tool. 


my marqui (Window, Y,X,box(T,L,D,W)) :- 
mouse down, 
marqui_ loop (Window, Y,X,Y,X), 
get_mouse (Window, ¥9, X9), % get final position of mouse 
reorder (Y,Y9,T,D), % reorder coordinates 
reorder (X,X9,1L,Wi). 


margqui_loop (Window, ¥,X,¥1,X1):- $ if released then terminate 
mouse up, 
J 


marqui loop (Window, Y,X,¥Y1,X1):- % while the mouse is down 
get mouse (Window, Y9,X9), $ get new position 
redraw pic (Window,Y,X,Y1,X1, Y¥9,X9), z update screen image 
marqui_loop (Window, Y,X,Y9,X9). % loop round 


redraw pic (Window, Y,%,Y0,X0,YC,X0):- & mouse didn't move 
l , l 


redraw _ pic (Window, Y,X,Y1,X1,Y9,X9) :- 


draw box (Window, Y,X,Y1,X1), % draw old box 
draw_box (Window, Y, X, Y9, X9). & draw new box 
draw box (Window, YO, X0, Y9,X9) :- $ draw in xor mode, grey box 


reorder (Y0,Y9,T,D), 
reorder (X0,X9,L,W), 
draw pic (Window, greypen (penmode (xor,box(T,L,D,W))). 


reorder (A,B,A,Gap) :- % maybe upwards drag 
A < B, 
t 
-r 
Gap is B--A. % use integer subtraction 
reorder (A,B, B, Gap) :- 
Gap is A--B. % use integer subtraction 
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Note; mouse pos will fail if the mouse goes outside the viewing pane, causing cragger and 
my marqui to fail. This will leave a copy of the last grey box on the screen, which will go away 
on the next refresh. Thus, on failure, we should invalidate the viewing pane. In practice, this 
failure may be undesirable, and we could introduce an extra program, mouse_in_ view, as 
defined below, to replace mouse _pos, So that if the mouse is dragged outside the viewing pane. 
we will get a series of beeps until it is brought back into the viewing pane. 


mouse _in_view (Window, Y,X):~ % get next mouse position 
get mouse (Window, Y,X), % mouse is in viewing pane 
! 

mouse _in_view (Window, Y,X):- % first clause failed 
mouse _in view(Window, Y,X). % just loop and try again ! 


This idea can be extended to restricting the ‘acceptable’ mouse coordinates to those inside any given 
Rectangle in the drawing area or viewing pane. | 


For example: 


oe 


restrict mouse (Window, Y, X, Rectangle) :- 
get_mouse (Window, Y, X), 


get a valid mouse position 
get next mouse position 


yo 


pt_in_box(Y,X,Rectangle), % mouse inside rectangle ? 
t 

restrict mouse (Window, Y, X,R) :- x first clause failed 
restrict mouse (Window, Y,X,R) . % just loop and try again! 


The Rectangle term is of the form box(T, 1,2, 4) 


ct in box isa primitive described later in this chapter, which tests to see if a point lies insic2 2 
given rectangle. 
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Edit Tools 


The following section is for programmers wishing to write tools that allow keyboard input of text 
into graphic windows using edit fields. 


Associated with each graphic window is a ‘'movable' text editor. This editor can be invoked at any 
position within the viewing pane. However, at any one time at most one edit field can be active, 
and all keystrokes will be entered into this edit field. If and when this editor is closed and moved 
to another place any text in the edit field must be extracted and saved. You will of course usually 
arrange for this text to remain displayed on the screen in the position it was originally typed 


There are two primitives that enable you to develop tools that open, prefill and extract information 
from edit fields in graphics windows: 


agit Line for a line of text 
ecit_box for several lines of text in a rectangular box. 


Tne edit field is closed by a mouse click outside the edit field but still in the graphic window. A 
click outside the graphic window will not close the edit field. i 


If the user clicks in either of the scroll bars or the viewer, then the viewing pane will scroll as 
usual. The edit field is still active (even though its screen position may have changed). 


Clicks elsewhere will be dealt with by the system, for example the selection of pull-down menu 


items. In the particular case of the Fonts menu, the edit field's text will be updated to reflect any 
change in font, style or size. 


If the click generates a dialogue or selects another window, then the whole graphic window 1s 
ceactivated, but the edit field will still be active when the graphic window is reselected,. You can 
override this behaviour by including a call toa shut_down_edit program in your actdeact 
program. This program would see which tool is currently selected, and if it was an ‘edit’ tool, call 
its close edit program directly. 


If a tool has opened an edit field in a graphic window then the tool's close_edit mode program 
is called by the system when the edit field is closed. This call should explicitly extract the entered 
text using the get_ text primitive, otherwise it will be lost. Of course, it is the responsibility of 
the programmer to Store the text appropriately. 


Note 


Due to the limitation on the length of an atom, the maximum amount of text that can be edited in any 
single edit field is 255 characters. 
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28.14 edit box - open an edit rectangle 


edit box (window, rectangle, just) 
edit box (window, rectangle, just, text) 


ARGUMENTS 
window : atom, name of graphics window 
rectangle : rectangle of the form cox (T, L, D, #) 
just : integer, text justification 
text : atom, initial text for edit field 

USE 


Opens an edit field in the graphics window with the position and size indicated by the rectangle 
argument. Any text typed at the keyboard will now automatically appear in this box. 


The text font, face and size to be used can be set by the set_gfonz primitive descnbed below. 
otherwise the window's current font, face and size wiil be used (which may be changed by the user 


from the Fonts menu). 


The just argument must be one of the integers 0. 1 or -1, representing left, centre or righ: 
justified text respectively. 


The four argument form of edit box initialises the edit field with text. This allows an oic 
edit field to be reactivated, for example. If the texz argument is not given, the edit field will ce 
displayed initially empty. 


EXAMPLE 1 


The following program defines a tool =;_edit which opens an edit field. When the edit field is 
closed, the tool takes the contents of the edit fieid anc adds a picture of it as a user-devined picture. 
which in this case is the text inside a grey box, ‘inset to resemble a display border. 


my edit (Window, Y,X,Mod) :- 
maroui (Window, (Y,X),Rect:, 
edit box (Window, Rect,0). 


ov! 


get users marqui 
open new edit rectangle 


alt? 


close edit field 
get details of edit field 


my edit (close_edit, Window) :- 
get_text (Window, Details), 
ument: E 28 Tool Buildin create a picture description 
gensym(my_edit_box,Name), generate a name for new pic 
add_pic (Window, Name, Desc}. x and add it to the window 


RP AO he 


ve 


Nd 


make desc (text (Font, Face, Size, EdBox, Text), 
user pic(Font, Size, Face,=£dBox, Texc, Border)):- 
p % return the picture to add 
inset box (EdBox, (-10,-10),3order). % get size of outer border 


user pic(Font, Size, Face, box(T,L,D,W), Text, Border), 
frextbox (Font, Size, Face,T,L,D,W,0,Text),greypen(thick (Border))]). 
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Notes 


l}. user pic is the definition of the user defined form. It takes 6 arguments and returns an 
aggregate description of some text and a box. Border is always a term of the form 
box (T, L, D, W}. 


2. The get_text primitive (described later) returns Details from the edit field on closing. 


fan example of 
pe some text 
m entered using 


Aimy edit 


E i a peace 5 
PO i B EIAS ES ILE IIE 





EXAMPLE 2 


To re-edit a text picture which was added using my_edit, we could add a new first clause for 
my edit as follows. 


my edit (Window, Y,X,Mod) :- $ re-edit 'my edit’ picture 
find_pic (Window, Y,X,Name,Desc,Org), % get picture under mouse 
Desc=[user_ pic (Font, Size, Face, EdBox, Text, Border) ],% is it one of mine ?? 


del pic(Window, Name), % if so, delete it 

set _gfont (Window,Font,Face,Size}), $ setup the edit font 

edit box (Window, EdBox, 0,Text) . $ open edit rectangle with initial Text 
Notes 


1. We use set gfont to set up the edit field font details, see below. 

2. In the above program we look at the description of the picture under the mouse click, and if we 
recognise it as one of ours, we remove it and open an edit field initialised with the text found in its 
description. Then we rely on the previousiy given close_edit program to add a new picture 
with the edited text when the edit field is closed. 


These programs as stated do not preserve the original names for the edited pictures nor their 
position in the window. We could preserve all previous information by setting some properties 
(using set_ prop) when opening the edit field to indicate what state we are in, and then extending 


the close edit program. 
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28.15 edit line -setup editable line of text 


edit line(window, down, across, just) 
edit line (window, down, across, just, text) 


ARGUMENTS 
window - atom, name of graphics window 
down : integer, horizontal coordinate 
across : integer, vertical coordinate 
just : integer, justification 
text - atom, initial text for edit field 
USE 


1. Four argument use To open an initially empty edit line of text into which the user may type. Tne 
width of the edit field will expand as characters are entered. 


2. Five argument use To set up an editable line of text, initialised with tex, into which any 
subsequent keyboard input will go. The width of the edit field will initially be enough to dispiay 
the text, and will expand as new characters are entered. It uses the current font, face and size. 
This form of edit_line is generally used to re-edit a line of text in a similar way to the four 
argument form of edit _box (see above). 


EXAMPLE 
A tool that creates a single line text picture of some entered text might be defined as follows. 


new edit (window, Y, X,Mod) :- 
edit line (Window, Y,X,0). 


ow 


open an edit line 


close the edit line 

extract the text details from the edit 
construct a description 

generate a name for new picture 
add the picture to the window 


new edit (close_edit, Window) :- 
get_text (Window, Details), 
make desc2(Details,Picture), 
gensym(my_edit_item,Name), 
add pic(Window, Name, Picture 


ge oe 


of 


0 ow 


make desc2 (text (Font, Face, Size, box(7,L,D,W) , Text). 
text (Font, Size, Face,T,L,Text)).- s return the description of a line of text 


(set_text retums the Details from the edit field on closing - see below.) 
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28.16 get_text - return text editor details 


get text (window, details) 


ARGUMENTS 

window : atom, name of graphic window 

details : variable, will be unified with a term giving text details 
USE 


To extract the details of the text entered in an edit field. This will be used in the close edit 
program for an edit tool to enable a picture to be constructed based on the text entered in the edit 
field. details will be unified with a term of the form 


text (Font, Face, Size,box(T,L,D,W) , Atom) 
where the box term describes the enclosing rectangle of the text and Atomis the text. 


Note 

Due to the limitations on the length of an atom, the maximum amount of text that can be extracted is 
255 characters. If more text than this has been entered, only the first 255 characters will be 
returned in Atom This effectively sets a limit on the size of an edit field. 


28.17 get_gfont - get current font details for graphic window 


get _gfont (window, font, face, size) 


ARGUMENTS 
window : atom, name of graphics window 
font : Variable, will be bound to name of font 
face : variable, will be bound to font face 
size : variable, will be bound to point size of font 
USE 


To get the current font details of a graphic window. This is useful for example, to implement user 
defined pictures which reflect the current font. 
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28.18 set _gfont -set font details for edit field 


set gfont (window, font, face, size) 


ARGUMENTS 
window : atom, name of graphics window 
font : atom, name of font 
face : integer, font face 
size : integer, size of font 
USE 


To set the font for a graphic window and, if open, its current edit field. 


The Anatomy of a Font 


Each character in a font is defined by pixels arranged in rows and columns. This pixe! arrangement 
is called a character image. 


The base line is a horizontal line coincident with the bottom of each character, excluding descencers 


(the ‘tails’ of letters such as y, g or j). The character origin is a point on the base line used as a 
reference location for drawing the character. 


Conceptually the base line is the line that the pen is on when it starts to draw a character. and th 
character origin is the point where the pen starts drawing. 


Cy 


The ascent is the distance from the base line to the top of the font rectangle, and the Jescer 
the distance from the base line to the bottom of the font rectangle. 


tt 


Ml 


maxwidth is the maximum character width for the font, and is therefore the greatest distance tn2 
pen will move when a character is drawn. 


The leacizg is the amount of blank space to draw between lines of single-spaced text -- the 


number of pixels between the descent line of one line of text and the ascent line of the next inec: 
text. 


@—--sracter width —> 






ft 
tN 
f} 
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rt 


base line 


character origin 


descent line 
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28.19 font_info - get characteristics of current font 


font_info(ascent, descent, maxwidth, leading) 


ARGUMENTS 


ascent : variable, will be bound to ascent height of current font 
descent : variable, will be bound to descent height of current font 
maxwidth : variable, will be bound to maximum width of current font 
leading : variable, will be bound to distance between lines 


USE 


To find out the characteristics of the current font. 


28.20 text width - get width of atom for a given font 


text width (text, font, face, size, width) 


ARGUMENTS 

text : atom, text string 

font : atom, name of font 

face : integer, font face 

size : integer, size of font 

width : variable, will be bound to pixel width of atom 
USE 


To find out the pixel width of some text using a given font, face and size. This is 
useful in calculating how much space to allow for text which is to be inserted in a text based 
picture. The width is the sum of all the individual character widths. 
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Miscellaneous Rectangle Primitives 


MacPROLOG provides a set of miscellaneous primitives to manipulate rectangle terms efficiently. 


28.21 inset box -inset a rectangle 


inset box(recti, point, rect2) 


ARGUMENTS 
rectl : a rectangle of the form box (T, L, D, W) 
point : a point pair of the form (DY, DX) 
rect2 : variable, will be bound to a rectangle term 
USE 


To ‘inset’ a rectangle in a positive or negative direction. This shrinks or expands the inital 
rectangle. The left and right sides of the rectangle rect 1 are moved in towards the centre of the 
rectangle by DX; the top and bottom are moved towards the centre by DY. If DY or DX are negauve, 
the appropriate pair of sides is moved outwards instead of inwards. The effect is to alter the depth 
and width of the rect 1 by 2*DY vertically and 2*DX horizontally, with the resulting rectangie. 
rect2, remaining centred in the same place as recti. 


Examples 
The call 


inset box (box (0,0,100,+00), (20,30), final_box) 
would result in final box being bound to the term 

box (20,30, 60,40). 
The call 

inset box (box(15,15, 100,100), (-20,-30),final_box) 
would result in final_box being bound to the term 


box (-5,-15,125,145). 


355 


28 : Tool Building 


28.22 offset_box - offset a rectangle 


offset_box(rectl,point, rect2) 


ARGUMENTS 
rectl : a rectangle of the form box (T, L, D, W) 
point : a point pair of the form (DY, DX) 
rect2 : variable, wili be bound to a rectangle 
USE 


To ‘offset’ a rectangle in a positive or negative direction. This moves the initial rectangle in both 
the vertical and horizontal directions. rect 1 is moved by DY vertically and by DX horizontally. 
If DY or DX are positive, then the movement is to the right and down, if either is negative, the 
corresponding movement is in the opposite direction. The rectangle retains its shape and size; only 
its position changes. 
Examples 
The call 

offset_box (box (0,0,100,100), (20,30), final_box) 
would result in final box being bound to the term 

box (20,30,100,100). 
The call 

offset _box (box (0,0,100,100), (~20,-30),final_box) 


would result in final box being bound to the term 


box (-20,-30,100,100). 
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28.23 intersect box -form the intersection of two rectangles 


intersect box(rectl,rect2,rect3) 


ARGUMENTS 
rectl : a rectangle of the form rox (T, L, D, #) 
rect2 : a rectangie 
rect3 : variable, will be bound to a rectangle 
USE 


To calculate the rectangle that is the intersection of two rectangles. Rectangles that touch ata line or 


a point are not considered intersecting, because the:r intersecting rectangle does not enclose any 
points. If the rectangles do not intersect the call fails. 


Examples 
The cali 


intersect box (box(0,0,100,2°2 -bOx(=2 50, 106,200); Fanai eei 
would resultin final _kox being set to 


Bex(0, 504505 


én 


os ee 
The call 
intersect box (box (0,50,150,52),box(-=2,50,100, 25° Eina os) 


would also result in finai_box being set to 


box (0 -50;50,50) . 
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28.24 union_box - form the union of two rectangles 


union box(rectl, rect2, rect3) 


ARGUMENTS 
recti : a rectangle of the form box (T, L, D, W} 
receZ ‘a rectangle 
rect3 : variable, will be bound to a rectangle 
USE 


To calculate the smallest rectangle that encloses two rectangles. 


Examples 
The call 


union_box (box (0,0,100,100) , box (-50,50,100,100), final_box) 
would result in final_box being bound to 

pox (-50,0,150,150). 
The call 

union box (box (0,50,150,50) ,box(-50,50,100,150), final_box) 
would result in final_box being set to 


box (-50,50, 200,150). 
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28.25 pt in box -test if a point is in a rectangle 


pt_in_box(point, rect) 


ARGUMENTS 

point : a point pair of the form (Y, X) 

rect : a rectangle of the form pox (T, L, D, #) 
USE 


To determine whether the pixel below and to the right of the given coordinate point 1s enclosed in 
the specified rectangle, rect. The call succeeds if the pixel lies in the rectangle, and fails 
otherwise. For example 


pt_in_box((2C,30),box(C,9, 40,59) ) succeeds, 
but 
pt_in_box((20,20),box(--0,-10, 22, 29)) fails. 


Note 

Because of the way that points and rectangles are handled in MacPROLOG, points on the left anc 
top edges of a rectangle are considered to be ‘inside’, whilst those on the bottom and right edges 
are considered to be ‘outside. 

For example 


pt _in_box((C,=),box(0,¢, 10,10) ) | succeeds. 
and pt _in_box((S,°),box(0,2,16,10)) succeeds, 
but 

pt. A boxis al box (2; 2410, 20)) fails, 
and pt_in_box((10,5),box(C,9,10,10)) fails. 
28.26 box in_box -test if one rectangle is in another rectangle 

box in_box(rectl, rect2) 
ARGUMENTS 

recti : a rectangle of the form box (T, L, D, 1) 

recz2 : a rectangle of the form box (T, L, D, ™) 
USE 


= 
i 


To determine whether the rectangle specified by recz is enclosed in the rectangle. rect 2. The 
call succeeds if the first rectangle lies in the second rectangle, and fails otherwise. 
For example 


box in box (box (10,10, 20,30),box(0,0,40,50)} succeeds, 
but 
box in_box(box(10,10, 20,30) ,box(-10,-10,20,30)) fails. 


Note that the comments made above about points on the edges of a rectangle also apply here. 
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29 Implementing an Application 
In this chapter we explain various facilities of MacPROLOG that are useful for applications. 


29.1 Execution on loading 


If a program file contains a definition for a unary relation ‘<LOAD>' this program will be called 
immediately after the file is loaded. The single argument to '<LOAD>' has no meaning and will be 
ignored. On completion of the evaluation of the '<LOAD>' call, the '<LOAD>' program code will 
be deleted so that a subsequent load will not result in a second call to '<LOAD>'. The next 
program file you load can contain another definition for '<LOAD>' and this will be called when 
the file load is complete. Again the definition of '<LOAD>' will be deleted on return from the call. 


This automatic calling of the '<LOAD>' program occurs after the loading of both source and object 
code programs. 


(See also section 29.1.5 for how to save a '<LOAD>' program.) 


29.1.1 Setting up new menus 


The execute on load facility can be used to set up menus suitable for an application on loading of 
the application. For example, suppose that you had an application which needed to have two 


menus labelled Database and Interrogate. Include in the source of your application a 
definition of the form: 


'<LOAD>' (Ignored_arg) :- 
install _menu('Database', ..... /* list of menu items */), 
install _menu('Interrogate’,..... /* list of menu items */). 


install_menu is a primitive for manipulating the menu bar, described in the chapter on Menu 
Handling. Remember that '<LOAD>' must be defined as a unary relation even though the 
argument has no role. 


On loading this application, menus named Database and Interrog ate will be added to the 
menu bar. As explained in the chapter on Menu Handling, your application should also contain 
definitions for the relations Database' and 'Interrogate' because these relations will be 
called when items from these menus are selected. | 


For example, if the Database menu contains an item Enter, which is to allow users to enter 
data via a modal dialogue, your program should contain a definition of the form: 


‘Database (*Enter*) <= 
mdialog(....), ; / *call to dialogue construction primitive 
with parameters describing the dialogue * / 
add _data(....). /* call to remember the entered data */ 
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29.1.2 Changing menus 


As well as extending the menu bar, you can also delete or modify existing menus on loading. Just 
include the appropriate calls to the menu handling primitives in your '<LOAD>' definition. 


For example, toremove Find definition... from the Find menu, include the call 


install menu('Find', ['What tco find.../W', 
‘Replace & find next/R', 
‘Find 262cyE"; 
'Find s¢lection/=')) 
The use of exactly the same names for the preserved menu items is important. In order to 
completely remove the Find menu without giving alternatives give the call: 


kill menu ('Find') 


WARNING: do not delete or change the File or É menus. These menus must remain as the: 
are. They provide the interface to the Mac system and the entries and their relative order must te 
preserved. You can delete items from or completely remove any of the other MacPROLOG menus. 


29.1.3 Extending the MacPROLOG menus 


You can also extend menus on loading by including calls to extend_menu. If you use this 
facility to extend a MacPROLOG menu vou must implement the new menu item. Normally yc- 


would do this by providing a new definition of the menu title relation in the loaded program. 


However, you cannot modify the definitions of the Zdit', ‘Find’, ‘Winccws' anc 
'S--a1' relations as their definitions are protected. For an extension of any of these menus, sc: 
with an item New command, just include a cefinition for the no argument relation Nev 
command' in your program. When the New command item is selected, your definition for 22 


will be called. This is because each of the Edit, Find. Windows and Eval menu definitions 
has a last clause to handle unrecognised menu items by calling the item. 


For example, ‘Eval' has a last clause 


‘eval’ (ltem):-1tenm. 


29.1.4 Defining operators 


An application that needs to use other than the precefined operators for user input or for message 
output must use a '<LOAD>' program to declare the operators on loading. Just include the 
appropriate sequence of op calls in the body of the '<LOAD>' clause. 


For example, the definition 
'<LOAD>' (X) :- 
op (600, xfx,@), 
op (550, fx, [$, #]) . 


will set up @ as a non-associative infix operator, and $ and # as non-associative prefix operators. 
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29.1.5 Saving the object code of a '<LOAD>' definition 


As described above, when you load a program with a source definition of '<LOAD>'‘ this 
definition will be executed on completion of the load. However, because the object code of the 
definition of the relation '<LOAD>' is deleted immediately after it has been executed, there will be 
no definition of ‘<LOAD>' if you save the object code immediately after loading the source. 


Before you save the program in object code form, you must force a recompilation of the program 
window in which '<LOAD>' is defined. You can do this by adding and deleting a space in the 


window and then recompiling using the Check program command of the Eval menu. Now 


an object code definition of '<LOAD>' will be in the memory of the computer ready for saving as 
part of a compiled application. 


29.2 Modifving the commands of the File menu 


Although you cannot alter or remove the File menu you can change the effect of the 
Reinitialise... and Quit commands of the menu. 


If you have a definition for a 0-argument relation '<REINIT>' this program will be called when 


the Reimitialise... command is selected. The normal dialogue allowing you to delete ali source 
windows or all source windows and all currently loaded object code will not be displayed. 


Similarly, you can have a definition for a unary relation '<QUIT>'. As with '<LOAD>' the 


single argument is ignored. This program will be called when the Quit command is selected and 
before MacPROLOG is exited. With a suitable definition for '<QUIT>', an application can save 
the state of the clause data base or the contents of certain windows before the exit. 

Even if you provide a definition for '<QUIT>' you will still be asked if you want to save your 
program should you have typed into any of its edit windows since the last Save... If you elect to 
do the save, your '<QUIT>' program will be called after the save is completed. 


NOTE : You cannot prevent the exit from MacPROLOG once the Quit comand has been selected. 
You will exit even if your '<QUIT>' program fails or aborts. 
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29.3 Error handling 


When an evaluation error occurs a MacPROLOG program is called to handle the error. The 
program is called with two arguments, an integer error number and the call term. If you include in 
your application a definition of the relation '<ERROR>', which takes the same two arguments, 
your program will be called instead of the default error handler. 


As an example, the following program defines a user error handler very similar to the one supplied 
in the MacPROLOG programming environment (see also the section below on the errmess 
primitive). | 


'<ERROR>' (Id, Call):- 
errmess({Id,Message), !, 
mdialog(S0, 50,200,380, 


[buttont 9:305; 20, 09" Succeed Jy 
bDüttont?5,;305; 20r 635p Fail J; 
button (65,505; Z0; Go, "ELOD Ty 
text( 5, 60, 24,240,wsea({'ERROR:',Messagej), 
text(41, 60, £2,240,writeq(Call)), 


rOont Sr. Bo 80y Sey Uly 
Bun), 
Btn = 2 ~> abort. 


The ! immediately after the call to errmess is necessary to avoid picking up the default error 
message on backtracking. 


29.3.1 The errmess primitive 


errmess is a primitive that you can use to pick up an appropriate message string for the identified 
error. See Appendix A for the errmess program. 


Notice in particular that 2 is the identifier for the error ‘No definition for relation’. If you want this 
error to automatically result in a failure of the call without the display of an error message dialogue, 
add a first clause: 

'<ERROR>'(2,Call):-!,fail. 


to your error handler program. You might also want to handle error 13 in this way. 
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29.4 Shipping an application 


You must obtain a special licence from LPA to enable you to distribute an LPA MacPROLOG™ 
application. If you would like further details of this licence please write to: 


OEM Licences 

Logic Programming Associates Ltd. 
Studio 4 

The Royal Victoria Patriotic Building 
Trinity Road 

London SW18 3SX 

England. 


With the licence you will be supplied with a special runtime version of MacPROLOG that you can 
include with your distributed application. You will also receive instructions on how to modify your 
application so that it will run outside the MacPROLOG programming environment, using only the 
runtime version of MacPROLOG. 
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Appendices 


The exrrmess Primitive 


errmess (0, ‘Number argument needed’). 
errmess(1, 'Arithmetic error’). 
errmess(2,'No definition for relaticn'). 
errmess(3, ‘Incomplete argument list"). 
rrmess(4,'Invalid predicate symbol'). 
exrmess(5, ‘Invalid form of call'). 


tg K 


Ht 


t4 


mess (10, 
mess (11, 
mess (12, 
mess (123, 
mess (14, 
mess (15, 
mess (16, 
mess (i7, 
mess (18, 
mess(19, 
mess(20, 
mess (21, 
mess (22, 
mess (23, 
mess(24, 


ty 


a any ae ee ee ee ee ee es ee ee ed ee ee | 
ty HY FY be ty Fe te Fe ty ry Fe Ry oe ty 


Om Dm D DM D D DD DD O MD Dh D OD DW Do MD DO 


H 
4 H 


e 


TE 


tr tH si ott oh 


ooomd 2 OD 


rmess(6, 'Syntax error'). 
mess (7, 'Error in compilaétion'). 
mess (8, ‘Structure too deep'). 
mess(9,'Error in assembly'). 


EFEO “in. -Jambaa.’).. 

‘Bad lambda expression'). 

"Format expression error'). 

‘Invalid form of use'). 

‘Cannot add clause for ccxrriled relaction'). 
‘New window name alreacy used’). 

‘Cannot compile vrogram r interpreted relation’). 
"Cannot compile program e prim.c ove). 

"Error in graphics’): 

tError dm printso ye 

'ETror in decompilation r 

'Text overflow in window (max 32K)'). 


-~ 
= h 
_— — 
~ 

- m 
- w 


"Invalid picture descristicn'). 
‘Duplicate picture name'} 
'No definition for graphics verb'). 


mess (-23, ‘Directory is full’). 
rmess (-34, 'Disk is full'). 

mess (-35, 'No such volume'). 
rmess(-36, 'Disk I/O error'). 
mess(-37, 'Bad name error ¢2¢'). 
rmess(-38, 'File not open'). 
rmess(-39, 'Read past end of file'). 
rmess(-40, ‘Invalid file position’). 
rrmess(~42,'Too many files'). 

yo Fe. Hot Found”) 


errmess(-44, 'Disk write protected'). 
errmess(-45, 'File is locked'). 

errmess(-46, 'Volume is locked'). 

errmess{-47, 'File is already open'). 
errmess(-48, 'Renamed file already exists"). 
errmess(-49, 'File already open for writing'). 
errmess(-51, 'Bad path id"). 

errmess(-52, 'Seek error'). 
errmess (-53, 'Volume not on line (ejeqed) '). 
errmess(-54, 'File permission error'). 
errmess(-56, 'No such drive'). 

errmess(-59, 'SERIOUS ERROR - PLEASE REPORT'). 
errmess(-60, 'Directory corrupted'). 
errmess(-61, 'Write permission error'). 


errmess (Id,Message) :- 
concat ('error: ‘,Id,Message). 


Appendix B 
ASCH Character codes on the Macintosh 


space - 32 
I =- 33 
"= 34 
# -35 
$ - 36 
f -37 
Ç - 38 
‘= 39 
( - 40 
)- 41 
* =- 42 
+- 43 
, - 44 
- - 45 
. ~ 46 
/ - 47 
0 - 48 
1 - 49 
2 - 50 
fa Meas) | 
4 - 52 
9-53 
6 - 54 
?- 55 
8 - 56 
9 - 57 
- = 58 
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a - 97 
b - 98 
c- 99 
d - 100 
e - 101 
f - 102 
g - 103 
h - 104 
i - 105 
j - 106 
k - 107 
I - 108 
m - 109 
n- 110 
o- 111 
p- 112 
g - 113 
r- 114 
s- 115 
t- 116 
u - 117 
u - 118 
W ~ 119 
H ~ 120 
y - 121 
Z - 122 
{ - 123 
| - 124 
}- 125 
~ = 126 
del ~ 127 


A - 128 
A - 129 
Ç - 130 


4 


É - 131 
N - 132 
0 - 133 
Ü - 134 
ú - 135 
à - 136 
a - 137 
a - 138 
& - 139 
@ - 140 
Ç- 141 
é - 142 
è - 143 
ê - 144 
- 145 
146 
147 
148 
149 
~ 150 
- 151 
- 152 


oe © p = = =~ = M: O 
| 


© 
i 
— 
LA 
tA 


Öö - 154 
0 - 155 
ú - 156 
ù - 157 
ü - 158 
ü - 159 
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*- 160 
° - 161 
¢ - 162 
£ - 163 
§ - 164 
e - 165 
q - 166 
B - 167 
® - 168 
© - 169 
es TIO 
ee I 
eae: e 
æ =- 173 
FE - 174 
5 - 175 
oo - 176 
t= 177 
<- 178 
2- 179 
Y- 180 
p- 181 
ð - 182 
=~ 183 
TI - 184 


w- 185 


f- 186 
a - 187 
0 - 188 
Q - 189 
te - 190 
g - 191 


¿ - 192 
i - 193 
~ - 194 
V - 195 
f - 196 
s - 197 
A - 198 
» - 199 
« - 200 
ww. ~ 201 
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Appendix C 
MacPROLOG Reserved Property/Object Names 


You should not use any of the following as a property name. They are used by MacPROLOG for 
special purposes. If you use them for your own properties you may affect the behaviour of a 
MacPROLOG primitive, or a menu command of the programming environment. 


‘ARITY' 
*BOX' 
‘CLAUSES ' 
"CLIPP IC 
“CURSOR 
'DATAREL' 
'DEFINWIN' 
“ECHOT” 
“GRAPHIC” 
"HELP ’ 
"INFOWIN ' 
rLNP OT" 
'MODE ' 

' MODULE ' 
"OLD? 
“OUTPUT: 
'DISPLAY' 
*DISPLAYT' 
"INPUT? 
"ANPUT: 
“PAPH” 
'ONAME' 
"OP LC" 
"QUERY '' 

' SNAME ' 

geod sap OL ON Sie i iy 
"SUFFIX-VALUE' 
*SYNTAX' 
"WINDCw}' 
*2STEP-FLAG? ' 
reoler=OUERY?* 
'<OP>' 


The following are reserved Object names. 
'DGW' 


'OUTWIN' 
rPCLIP=PICI" 
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MacPROLOG Predeclared Operators 
The following are the predeclared operators of MacPROLOG Edinburgh syntax. 


Priority Type Name 


1200 
1200 
1200 


1200. 


1150 
1150 
1100 
1100 
1100 
1050 
1000 
900 
900 
900 
700 
700 
700 
700 
700 
700 
700 
700 
700 
700 
700 
700 
700 
500 
500 
500 
500 


xfx 
xfx 
fx 

fx 

fx 

fx 

xf 

xfy 
xfy 
xfy 
xfy 
fy 

fy 

fy 

xfx 
xfx 
xfx 
xfx 
xfx 
xfx 
xfx 
xfx 
xix 
xfx 
xix 
xfx 
xfx 
yÍx 
yfx 
yfx 
yix 


mode 
public 
? 


-> 


Paai 
li 


A en 


H A 


++tIAWMWVV IVA ET 


+ 


Priority Type Name 


500 
500 
500 
500 
500 


400 
400 
400 
400 
400 
400 
400 
400 
300 
200 


yix 
yfx 
fx 
£x 
£x 


yfx 
yfx 
yfx 
yfx 
yfx 
yfx 
yfx 
yix 
xfx 
xfy 
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/\ 
\/ 
+ 


\ 


*kx* 


// 
«< 

»> 
<< 
>> 
mod 
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Appendix E 
Compatibility with Quintus PROLOG 


The following primitives of Quintus PROLOG are not supported in LPA MacPROLOG™, 


absolute _file name 
ancestors 

break 

‘Ct 
character-count 
compile 

current atom 
current input 
Current. key 
Current Qutput 
urrent predicate 
current stream 
cenug 

debugging 

depth 
ensure_loaded 
erase: 
expand_term 


fileerrors 

flush output 
foreign 

foreign file 
format 

gc 

gcguide 

incore 

instance 

leash 

Jibrary directory 
line count 

line position 
load_foreign_files 


manual 
maxdepth 
nodebug 
nofileerrors 
noge 

no style_check 
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open null stream 


portray 
prince 

prompt 
reconsult 
recorda 
recorded 
recordz 
reinitialise 
restore 

save program 
set 1npürt 
set output 
source file 
statistics 
stream code 
Stream position 
Style check 
subgoal_ of 


term expansion 
trimcore 
ttyflush 
ttyget 

ttygetO 

ttynl 

ttyput 

ttyskip 

ttytab 


unix 
user-help 
vars 


write canonical 
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Appendix F 
Graphic Editor Source 


This ‘Graphic Editor’ program is included as source code on the LPA MacPROLOG disk (‘Editor 
Source’). It demonstrates the various graphics, menu and dialogue primitives available in 
MacPROLOG, and it also serves as an example of a complete graphics application written in 
MacPROLOG. 


When you run this program a help file is loaded at the beginning giving instructions on its use. You- 
will see the 'Graphic Editor’ graphic window, which is created by this program, together with its 
various tools which draw and manipulate shapes. 


The complete source text of the 'Graphic Editor’ is reproduced here with additional comments and 
explanations. 


There are six program windows in the source text. These are 


Graphic Editor : start 
Graphic Editor : menus 
Graphic Editor : dialogues 
Graphic Editor : tools 
Graphic Editor : rubber band 
Graphic Editor : misc. 


F.1 Graphic Editor : start 


This window contains the startup code for the program. We use the execute on load facility by 
defining the relation '<LOAD>' (which takes a single dummy argument). 


F.1.1 


The '<LOAD>' program creates the Graphic Editor graphic window (by calling 
initial_gw) and then loads the help file using the t load primitive. This ‘help’ window is then 
resized, its font changed to Courier 10 point, made visible, and then finally brought to the front. 
(See the Window Handling chapter for details of these primitives.) 


'<LOAD>* (Dummy) :- 
initial gw('Graphic Editor'), 
tload('Editor Help'), 
wsize('Editor Help’, 70, 55, 215, 365), 
wfont (‘Editor Help', 'Courier',0,10), 
wshow('Editor Help’), 
wfront (‘Editor Help'). 
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F.1.2 


The initial gw program calls wgcreate to create the Graphic Editor window. The 

init gensym calls are to initialise the picture names for the various graphical objects which wil 
be created. The ‘global values’ of the program are stored as properties, which are initialised here 
using set_ prop. The window's activation / deactivation program is defined to be menus, and 
winTools adds the graphic tools to the window (see below). 


initial gw(Name) :- 
wgcreate (Name, 50, 30, 250, 400, $6, 300, 309, 0, 1), 
init _gensym(userRRect), 
init _gensym(userRect), 
init_gensym(userLines), 
init _gensym(userPoly), 
init gensym(userOval), 
set crop('Grapnic Editor 
set prop('Graphic Editor 
set_prop('Graphic Editor 


i, *PENGlZ= "5 thin); 
l 
set_prop('Graphic Editor' 
t 
‘ 


"PENPSat', bilackren), 
‘STAs. y -2L5)% 
'ANGLE', 90), 

PILLS TCH"; Lea eay, 
"EILL y. Larey) 
TOVALLC ES 2H", 30), 
'OVALHIDTH', 30), 


set prop('Graphic Editor 
set ctrop('Graphic Editer 
set_prop('Graphic Editcr 
set prop('Graphic Editor 
gacztdeact (Name, menus),., 
winTools (Name), 

wfrent (Name). 


~- ~ ~ “= - ™ "~ ~ 


F.1.3 

The ‘actdeact’ program for the window defines what happens when the window is activated (i.e. 
becomes the front window) or deactivated. Here we simply kill the Graphic Editor menus when the 
window is deactivated, and reinstate them when the window is activated. This means the menus 


only appear on the menu bar when the Graphic Editor window is the front window. 


menus (activate, Name) :- 
penMenu, 
f£iliMenu, 
roundMenu. 


menus (deactivate, Name) :~- 
kill _menu('Round'), 
kill menu('’Pen’), 
kill menu('Fill'"). 
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F.1.4 


Tools are added to the window using the add_tools graphics primitive. A tool is defined by 
giving its program name and its graphical description, in a term of the form 


tool program(graphical_description) 


Note the user defined graphical forms for the graphical descriptions of some of these tools 
(lettera, myrect, etc.). The select, drag, enter _text, pic_infoand eraser tools 
are all predefined in MacPROLOG (see the Graphic Windows chapter). The rest are defined in the 
tools window of this program. | 


winTools (Window) :- 

add_ tools (Window, 

[select (arrow()), 

drag (dragger()), 

geLines ([ 

double ([lines([(28,5)}, (10,18), (16,26), (10,18), (28,5)]), 

fillcircle (28,5,2), 
filicircle (10, 18,2}, 
fillcircle(16,26,2), 


)), 
greypen (lines ([(28,5), (16,26), (28,5)])), 
}), 
enter _text (lettera (Window) }), 
pic_info(info_icon()), 
geRect (myrect (14,4,14,24)), 
geRRect (myrrect (14,4,14,24)), 
geOval (myoval (14,4,14,24)), 
geArc (myarc (14,4,14,24)), 
gePoly (double (grey ( 
fillpoly([(16,2), (24,30), (2,10), (30,10), (8,30)]))))-, 
eraser (rubber {)) 
J; 3). 
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F.1.5 
These are the user defined graphical forms which describe the graphical representations of the 


window's tools. Note that the get_pen details call (defined later) returns the current settings 
of the fill pattern, pen size etc. 


lettera (Name,Desc) :- 
get_gfont (Name, Fname,Fc,Size), 
Desc = text (Fname, Size,Fc,28,12,'A'). 


~vrect (T,L,D,W, Desc) :- 
get _pen_details(Size,Penpattern,Fillswitch, Pattern), 
on(Fillswitch-Prim, [hollow-box, filled-fiilbox]), 
Desc = Penpattern(thin (Pattern (Prim(T,L,D,W)))). 


sarrect (7; Lr D; W Desc; <= 
box_details(Oh,Ow), 
FI (Ons 5 -SOn):; /* Integer division */ 
// (CW, 5, Sow}, 
get _pen_details(Size,Penpatterr,Fillswitch,Pattern), 
on(Fillswitch-Prim, [hollow-box, filled-filibox]), 
Desc = Penpattern(thin (Pattern (Prim(T,L,D,W,Soh,Scw)))). 


myoval (T,L,D,W, Desc) :- 
get pen details (Size, Penpattern,Fillswitch, Pattern), 
on(Fillswitch-Prim, [holiow-~oval, filled-filloval]), 
Desc = Penpattern(thin(Fattern(Prim(T,L,D,W)))). 


svaro (TLD; W Dese) i= 
arc details(S,A), 
get pen details (Size,Penpattern,Fillswitch, Pattern), 
on(Fillswitch-Prim, [hollow-arc, filled-wedge])), 
Desc = Penpattern(thin(Pattern (Prim(T,L,D,W,S,A)))). 
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F.2 Graphic Editor : menus 


These are the menu installation programs, which will be called whenever the 'Graphic Editor’ 
window is activated. When each menu is installed the current setting is marked. 
F.2.1 


The Pen menu offers pen size and colour options, and also allows the switching on and off of the 
graphic window's viewer. 


penMenu:- 
install menu('Pen', 
{fthin,nilpen,thick, 
"Pen size...','(-;blackpen',greypen, '(-;viewer']), 


get _prop('Graphic Editor', 'PENSIZE', Size), 
markpen (Size), 

get prop('Graphic Editor', 'PENPAT',Pat), 
mark _item('Pen',Pat). 


F.2.2 


The Fill menu offers all the fill pattern options, and also allows the selection of filled or hollow 
objects. 


fillMenu:- 

install _menu('Fill', 
{filled, hollow, '(-;black',grey,lgrey, dots, check, 
crosses, diag, diamonds, horiz, rdiag, speckled, 
stripesthin, stripesthick, 
waves,white,alpha,beta]), 

get prop(‘'Graphic Editor', 'FILLSWITCH', Switch), 

get_prop('Graphic Editor', 'FILL',Pattern), 

mark item('Fill',Switch), 

mark item('Fill',Pattern). 


F.2.3 


The Round menu allows the selection of the 'roundedness' of round rectangles, and the form of 
arcs. | 


roundMenu:- 
install menu('Round', ['Rectangle...', 'Arc...']). 


The actual menu programs follow. These will be called whenever the user selects one of the items 
from one of the menus. 
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F.2.4 


The Pen menu's Viewer option allows the window's viewer to be switched on and off. The 


Pen size... option generates a dialogue allowing selection of any pen size (the penvals 


definition is in the dialogues window of this program). The menu also offers two pen colours and 
some predefined pen sizes. 


*Pen' (viewer):- 
wfront (Name), 
marked item('Pen',viewer),!, 
unmark item('Pen',viewer), 
gviewer (Name,off). 


"Pen' (viewer):- 
wfront (Name),!, 
mark item('Pen',viewer), 
gviewer (Name,on). 


‘'Pen' (viewer) :-!. 


‘Pen'('Pen size...'):-!, 
 penvals, 
wfront (Name), 
inval_ tool _pane (Name). 


‘Pen’ (Item) :- 
update menu_selection(item, ‘Pen', 
{folacxvcen,greyren], 'PENPAT'),!. 


"Pen" (Item) :- 
get_prop('Graphic Editcs', ‘PENSiZz',Size), 
unmarkpen (Size), 
mark item('Pen',Item), 
set prop{'Graphic Editor", 'PENS:Z=', Item), 
wfront (Name), 
inval tool pane (Name). 


markpen (vensize{A,B)):-!, | 

mark item{'Pen!; Pen Siess") 
markpen (Size):- 

mark item('Pen',Size). 


unmarkpen (pensize(A,B)):-!, 
unmark item( ‘Pen’, *Pen size.:."). 
unmarkpen (Size) :- 
unmark_item('Pen',Size). 
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F.2.5 


The Fill menu allows the selection of either filled or hollow objects, and the selection of a fill 
pattern. 


"Eill" (Item) :<4 
update menu_selection (Item,'Fill',[filled,hollow], 
"FP ILUSWITCH* ) 4.2% 
'Fill' (Item) :- 
update menu _ selection (Item, 'Fill', 
[black, grey, lgrey, dots, check, crosses, diag, 
diamonds, horiz,rdiag, speckled, stripesthin, 
stripesthick,waves,white,alpha,beta], 'FILL'). 


F.2.6 


The Round menu generates a dialogue either to reset the round rectangle settings or the arc 
settings. The rrect vals and arcvals definitions are in the dialogues section of this 
program. 


"Round' ('Rectangle...'):-!, 
rrectvals, 
wfront (Name), 
inval_tool_pane (Name). 


"Round' ('Are...'):- 
arcvals, 
wfront (Name), 
inval_tool_pane (Name). 


F.2.7 
This is a generalised routine for updating the markings on a menu. 


update _menu_selection (Item, Menu, List, Property) :- 
on(Item, List),!, | 
get_prop('Graphic Editor',Property,Olditem), 
Olditem \= Iten, 
set_prop('Graphic Editor',Property,Item), 
wfront (Name), 
inval tool _pane (Name), 
remark (Menu, Olditem, Item). 


remark (Menu, Item, Item) :-!. 

remark (Menu, Old, New) :- 
unmark item(Menu,Old), 
mark _item(Menu, New) . 
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F.3 Graphic Editor : dialogues 


The dialogues here make use of the advanced dialogue features of MacPROLOG (see the Advanced 
Dialogues chapter). 


In each dialogue, integers must be entered, and we therefore associate with each dialogue a goal 
which checks that the user has typed integers (an ‘Extended Dialogue’). The call to mdialog does 
not succeed until this checking program has succeeded. 

If the user has not typed integers, a beep is sounded and a message is displayed. 


(The user may of course click on the Cancel button in which case the mdialog call fails.) 


Note the use of the pname primitive which converts a term into an atom which can then be 
displayed in a dialogue edit or text field. 


F.3.1 The Round Rectangle dialogue 


The current values of the oval width and oval depth for drawing a round cornered rectangle are 
stored as the "OVALWIDTH' and 'OVALZEPTH' properties of 'Graphic Editcz'. These are 
retrieved for display in the dialogue, anc they are then reset according to the user's input. 


rrectvals:- 
get_prop('Graphic Editor"; ‘OVALWIDTH',OW), 
pname (OW, Ovw), 
get orop(*Grapnic Edices*,; “OVALOEPTH", OD); 
pname (OD, Ovd), 
maie og (40; 270, 1507220; 
[butt onii20;20,20 7 r OK Y4 
Button-(1.207 140,22, 57,7 Cante rj; 
text (15, 20,20,19°, 'ZFound Rectangle Corners’), 
text. (45,.30,32; 107,’ Oval dentn:"),; 
edit (45,140,16,35,ivd, reac (Septh)), 
text (85,20; 3210p "oval width: tF; 
edit (85,140,16,25,2vw,read{Width)?})], 
Btn, intgs (Depth, iicth)), 
šet crop("Graphic Editer; *OVALAIDIN”, Width), 
set crop('Graphic Editcr', ‘OVALDEPTH',Depth). 


The program to check that positive integers have been entered. This must fail if the integer checks 
fail, so that control is returned to the dialogue. 


intgs (D,B, Depth, Width) :- 
integer (Depth), 
intecer (Width), 
Depth >= 0Q, 
Width >= 0,!. 


intgs (D,B, Depth, Widath)..-— 
beep (10), 
message('Please enter positive integers 
for the~Movai depth and width'), 
fail. 
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F.3.2 The Arc details dialogue 


The current values of the start angle and sweep angie for drawing an arc are stored as the 
'START' and 'ANGLE' properties of 'Graphic Editor '. These are retrieved for display in 
the dialogue, and they are reset according to the user's input to the dialogue. 


arcvals:- 

get_prop('Graphic Editor', 'START',STA), 

pname (STA,SA), 

get _prop('Graphic Editor', ‘ANGLE',AAA), 

pname (AAA, AA), 

mdialog(40,270,150,220, 
fhutton(i120,20,20;,60, OK") 
button (120,140,20,60, 'Cancel'), 
text (15,70,20,110, ‘Arc Details'), 
text (45,30,32,100, 'Start angle:'), 
edit (45,140,16,35,SA,read(Sangle)), 
text (85,30,32,100, 'Arc angle:'), 
edit (85,140,16,35,AA, read(Aangle))], 
Btn, intags (Sangle,Aangle)), 

set _prop('Graphic Editor’, 'START', Sangle), 

set prop('Graphic Editor', ‘ANGLE',Aangle). 


Check that integers have been entered for the angles. This is similar to the program for the Round 
Rectangle dialogue, except that negative integers are acceptable here, and a slightly different 
message is given for non-integer input! 


intags (D,B,S,A) :- 
integer (S), 
integer (A),!. 


intags (D,B,S,A):- 
beep (10), 
message('Please enter integers for the angles'), 
fail. 
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F.3.3 The Pen details dialogue 


The curpvals call picks up the current size of the pen. This is stored as the 'PENSIZE?’ 
property of ‘Graphic Editor', and may either be an atom such as thick or thin, ora term 
of the form pensize (Depth, Width). Some term manipulation is necessary to cope with 
these two possible formats for the pen size. 


penvals:- 

curpvals (Pnd,Pnw), 

mdialog (40,270,150, 225, 
[button (120,20,20, 60, 'Ok'), 
button (120,140,20,60, ‘Cancel'), 
text (15,80,20,100, 'Pen Size'), 
text (45,30,32,100, "Pen derzh:'), 
edit (45,140,16,25,nd, reac (Depth)), 
text (85,30,32,100, 'Pen wicin:'), 
edit (85,140,16,25,Pnw,reac(Width))], 
Btn, pintgs (Depth, “Width)), 

set prop('Graphic Editcr', ‘PENSIZE',pensize (Depth, eau) )< 


Check that positive integers have been entered for the pen details. 


pintgs (D,B,Depth, Width) :- 
integer (Depth), 
integer (Width), 
Depth >= 0, 
Width >= 0,!. 


pintgs (D,B,Depth, Width) :- 
beep (10), 
message('Please enter cositive integers 
for the~Mren depth and width’), 
fail. 


Find the current pen values for the dialogue. The pen size may be an atom, or a term of the form 
pensize (PD, PW), where PD is the pixel depth and FW is the pixel width of the pen. 


curpvals (D,W) :- 
get_prop('Graphic Editcr', 'PENSIZE',pensize(PD,PW)),-:, 
pname({PD,D), 
pname (PW, W). 


curpvals (D,W) :- 
get _prop('Graphic Editcr’, ‘PE:SiZE', Size}, 
unmark_item('Pen',Size), 
mark item('Pen', 'Pen size...'), 
Sighs (Size,D,W). 


Convert a pen size atom to actual size. (A thin pen is 1x1 pixels, a thick pen is 8x8 pixels, and 
anilpen has zero size.) 
sighs (chin, Iy IT] 


sighs (thick, '8','8'). 
Sighs (nilpen,'0','Q'). 
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F.4 Graphic Editor : tools 
These are the tool program definitions for the Rectangle, Round Rectangle, Oval and Arc tools. 
Each tool has a double, activate, deactivate and ‘click’ mode defined. 


The double mode is called when the user double clicks on the tool's picture. Here we give 
information on the tool using the help primitive. 


The activate mode is called when the tool is selected, and the deact ivate mode is called 
when the tool is deselected. In each of these cases we simply change the appearance of the graphic 
cursor. 


The click mode is called when the user clicks in the viewing pane of the window; in this case the 
appropriate graphical object is drawn (the drawing tool program is defined later). 


For rectangles, we use the 'RBOX' property of ‘Graphic Editor" to signal whether a round 
cornered or ordinary rectangle is to be drawn. 


F.4.1 Rectangle Tool 


geRect (double, Window) :- 
tool info('Rect'). 


geRect (activate, Window) :- 
gcursor (Window, pen). 


cseRect (deactivate, Window) :- 
gcursor (Window, cross_hair). 


geRect (Window, Y, X, Mod) :~ 
drawing tool (box, Window, Y,X,Mod) . 


F.4.2 Round Rectangle Tool 


geRRect (double, Window) :- 
tool info('RRect'). 


geRRect (activate, Window) :- 
set prop ('Graphic Editor’, 'RBOX',on), 
gcursor (Window, pen). 


geRRect (deactivate, Window) :- 
set_prop('Graphic Editor', 'RBOX',off), 
gcursor (Window, cross hair). 


geRRect (Window, Y, X,Mod) :- 
drawing tool (box, Window, Y, X,Mod). 
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F.4.3 Oval Tool 


geOval (double, Window) :- 
tool info({'Oval'). 


geOval (activate, Window) :- 
gcursor (Window, pen). 


geOval (deactivate, Window) :- 
gcursor(Window,cross hair). 


geOval (Window, Y, X, Mod) :- 
drawing tool {(oval,Winccw,Y,X,Mca). 


F.4.4 Arc Tool 


geArc (double, Window) :- 
toot Into Are’): 


geArc (activate, Window) :- 
gcuzsor (Window,pen). 


seArc (deactivate, Window) :- 
gcursor (Window,cross air 


ceArc (Window, Y, X,Mod) :- 
drawing tool (arc,Winccw, Y,X,Mcc). 


F.4.5 

Generalised drawing routine for tools. We use the mazqui primitive to establish the rectangie in 
which the graphical object is to be drawn. This Frame argument ts then passed to shave args 
which generates the appropriate graphical description of the object (see later). The definition of 
myadd_pic is in the misc window. 


drawing tool (Name, Window, Y,%,slod) :- 
maraui (Window, (Y,X),Frame), 
get pen details (Name, S:;name, Size, 
Penpaz= tern, Filicswitch, Pattern), 
on (Name (Fillswitch, Prim), 
[Any (hollcw, Any) ,box (filled, fillbox), 
oval (filled, filloval), 
arc(filled, wedge), poly(filled, fillpoly)j),', 
shape args (Name, Prim,rrame,Primandargs), 
myadd_ pic (Window, Synane, 
Size (Penpattern (Pattern(Primandargs)))). 


F.4.6 
Give information on tools using the help primitive. 


tool _info(Tool) :- 
help('Editor Tools Heip',Tool,''). 
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F.5 Graphic Editor : rubber band 


These are the tool definition programs for the Lines and Poly tools. We use the rubber band 
primitive (see stretch_a_line, defined later) to draw the lines for these tools. 


F.5.1 Lines tool 


geLines (double, Window) :- 
tool info('Lines'). 


geLines (activate, Window) :- 
gcursor (Window, pen). 


geLines (deactivate, Window) :- 
gcursor (Window, cross hair). 


geLines (Window, Yy0, Xx0, Mod) :- 
Initpt = (Yy0,xXx0), 
get_prop('Graphic Editor', 'PENSIZE',Size), 
get_prop('Graphic Editor', 'PENPAT',Ppat), 
actual size (Size,Sizebox), 
actual ppat (Ppat,Pattern), 
Pen = pen(Sizebox, Pattern), 
rubber band(Window, Initpt,Next,Pen), 
stretch_a_ line (Window, Next, [Next, Initpt],Pts,Mod,Pen), 
gensym(userLines,Syname), 
mvadd pic (Window, Syname, Size(Ppat (lines (Pts)))). 


F.5.2 Poly tool 


gePoly (activate, Window) :- 
gcursor (Window,pen). 


gePoly (deactivate, Window) :- 
gcursor (Window,cross hair). 


gePoly (double, Window) :~ 
tool _info('Poly'). 


gePoly (Window, Yy0, Xx0,Mod):- 
Initpt = (Yy0,Xx0), 
get_pen_ details (Size,Ppat,Fillsw,Fillpat), 
actual_size(Size,Sizebox), 
actual ppat (Ppat, Pattern), 
Pen = pen(Sizebox, Pattern), 
rubber band (Window, Initpt,Next,Pen), 
stretch a line (Window,Next, [Next, Initpt],Pts,Mod,Pen), 
gensym(userPoly,Syname), 
on(Fillsw-Prim, [hollow-poly, filled-fillpoly])), 
myadd pic (Window, Syname, Size (Ppat (Fillpat (Prim(Pts))))). 
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F.5.3 

This program adds another line to the lines drawn so far, by waiting for a mouse click and calling 
the rubber_band primitive. 

The second clause is to terminate the drawing when a ‘modifier’ key (e.g.Shift) is held down when 
clickin 

The third clause will be called if the user releases the mouse outside the window's viewing pane 
(this causes rubber band to fail). In this case the inval_box has the effect of erasing all the 
(temporary) drawing done so far. 


stretch_a_line (Window, Ptin,Sofar,F2nal,0,Pen) :~ 
wait click (Window, Ny,iix,Mod), 
rubber band (Window, Ptin, Ptout,=Fen),!, 
stretch a line (Window, tout, [Ptout |Sofar!, Final, Mod, Fen). 


stretch a line (Window, Last, List, List,4, Pen) :- 
M\= 0,!. 


stretch 4 line (Window,Al,2#2,A3,A4,A5) :- /* any args */ 
gview_pane (Window, Box), 
invali box (Window, Box), 
fail. 


F.5.4 
Convert a pen pattern to a hexadecimal atom, and convert a pensize to a "point’. 


actual a T keira see o ) 
SEreeer’?) ; 


actual size(thin,5ox(0,0,:,-)). 
actual size(nilpen,box(0,C,90,0)). 
actual size (thick,box(0,0,8,8)). 

actual size(pensize(D,W),rcox(0,0,D,")). 
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F.6 Graphic Editor : misc 


This is a collection of miscellaneous routines used in various parts of the program. 


F.6.1 
Pick up the round cornered rectangle and the arc properties. 


box details (Depth, Width) :- 
get _prop('Graphic Editor', 'OVALDEPTH',Depth), 
get_prop('Graphic Editor', 'OVALWIDTH', Width). 


arc details (S,A) :- 
get_prop('Graphic Editor', 'START’,S), 
get_prop('Graphic Editor', 'ANGLE',A). 


F.6.2 

The six argument form of get_pen_details returns the pen's various attributes as well as a 
suitable picture name (generated by gensym). 

The five argument form just returns the pen's current attributes. 


cet_ pen details (Name, Syname, Size,Penpat,Fills,Fpatt):-!, 
gensym (Name, Syname), 
get_pen_ details (Size,Penpat,Fills,Fpatt). 


get pen details (Size,Penpattern,Fillswitch, Pattern) :- 
get_prop('Graphic Editor', 'PENSIZE',Size), 
get _prop('Graphic Editor’, 'PENPAT',Penpattern), 
get prop('Graphic Editor', 'FILLSWITCH',Fillswitch), 
get_prop('Graphic Editor', 'FILL',Pattern). 


F.6.3 

The shape _args program retums a GDL description given a picture frame and the name of the 
graphical object. For a box object we need to add extra arguments if it a round comered box. 
Similarly, the start and sweep angles must be added to an arc description. 


shape args (box, Prim,box(T,L,D,W),Prim(T,L,D,W,Hgt,Wdth) ) :~ 
get prop('Graphic Editor', 'RBOX',Flag), 
Flag = on,!, 
box details (Hgt,Wdth) . 


shape args (arc, Prim, box({T,L,D,W),Prim(T,L,D,W,Start,Amount)):-!, 
arc details (Start, Amount}. 


shape args (Other, Prim,box(T,L,D,W),Prim(T,1L,D,W)). 
F.6.4 


This is a special form of add_pic needed by the Graphic Editor. Because the pen size may be in 
one of two forms, we cannot call add_pic directly. 


myadd pic (Window, Syname, Size (Penpat (Pat (Primandargs) ))):- 
Size = pensize(A,B),!, 
add_pic (Window, Syname, pensize (A,B, Penpat (Pat (Primandargs) ))). 


myadd pic (Window, Syname, Size (Penpat (Pat (Primandargs) ))):- 
add_pic (Window, Syname, Size (Penpat (Pat (Primandargs)))). 
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Map a relation over a list, 23 

Test if a menu item is marked, 122 

Mark a menu item, 121 

Draw a graphics marqui, 337 

Create modal dialogue, 147 

Find subterm corresponding to path, 56 
Modal dialogue item format descriptor, 147 
arenes dialogue, 132 


Modulus of one number relative to another, 39 
110, 147 

110, 138 

113 

336, 343 

Test if mouse is depressed, 344 

Test if mouse button released, 345 

Move a dialogue item, 155 

Ask an immediate yes/no question, 130 


String to term conversion, 66 
not, 15 

Select a new file name, 100 
Set pen to 0x0 pixels, 260 
bas a new line, 95 

1 


Non variable test, 25 
Remove a spypoint, 109 
Remove all spypoints, 110 
Negation as failure, 15 
Switch off tracing, 110 

A umber test, 26 


Ground the variables in a term, 32 


364 

Offset arectangle, 356 

Select a file name, 99 

List membership, 60 OW 
Operator declaration, 108 

Open a file, 101 

6, 108 

72 

True, 17 

Check box selection mode, 151 
Hollow oval, 236 

Check box selection mode, 151 


eon 
Cc 
T~ 


P 


Pascal programs 
paste 

Pattern definitions 
Pause 

pbutton 
pcheck 

pen 

penmode 
penpattern 
penscale 
pensize 
phrase 

pi 

pics in_box 
picture 
Picture dialogue items 
pic centre 
pic trame 
pic _ Anco 
pname 

poly 

Printer port 
prompt gread 
prompt read 
Properties 
pt_in_box 

pt in pic 
Pull down menus 
put 
put. con Cext 
put con text 
pút copy cell 
put copy cell 
put int val 
püt int vál 
put Tist 

pút list 

put nil 
put_nil 
put_real val 
put_real_val 
put_tpl 
put_tpl 

pwr 


Q 


qpic_frame 
qpic size 
QuickDraw 
'<QUIT>' 
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Paste text into a window, 166 

270 

ticks, 112 

Dialogue item format descriptor, 150 

Dialogue item format descriptor, 151 

Cursor descriptor, 334 

Set pen'’s drawing mode, 263 

Set pen to specified pattern, 272 

Scale size of pen, 262 

Set pen to specified size, 261 

Test if list can be parsed as a phrase, 32 

Get value of x, 49 

Find pictures in rectangle, 339 

Describe an imported picture, 253 

150, 231 

Get a picture's centre, 294 

Get a picture's enclosing rectangle, 294 

Graphic tool program, 315 

Get print name of a term, 69 

Enclosed object of connected lines, 244 

113 

Prompted read of ground term, 126 

ORNS read of hollow term, 125 
5 

Test if point is in rectangle, 359 

Test if point is in picture, 340 

116 

Write a character, 97 

C interface function, 188 

Pascal interface function, 211 

C interface function, 189 

Pascal interface funcuon, 212 

C interzace function, 188 

Pascal interface function, 211 

C intertace function, 189 

Pascal interface function, 211 

C interface function, 189 

Pascal interface function, 212 

C interface function, 188 

Pascal interface function, 211 

C interface function, 189 

Pascal interface function, 212 


Power to any base, 46 


Get picture's frame, 333 

Get picture's size in bytes, 333 
226 

Quit program, 362 
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radio 

rdiag 

read 

recall 
record pic 
Rectangle primitives 
Refresh a graphic window 
refresh now 
"<REINIT>* 
remember 
remove 
remove pic 
rename 
rename_item 
repeat 
replace pic 
resource 
res_ close 
res create 
res finish 
res items 
res open 
retract 
Fetractall 
retractx 
reverse 
reverse pics 
right thumb 
Rounded rectangle 
rubber 
rubber band 


Dialogue item format descriptor, 278 

Set fill pattern to reverse diagonal lines, 278 
Read a term, 92 
Recall a named value, 87 

Add picture to window's list, 329 

355 

320 

Force a redraw of a graphic window, 327 
Reinitialisation program, 362 

Store a named value, 87 

Remove item from a list, 61 

Remove picture from window's list, 330 
Rename a file, 106 

Rename menu item, 122 
Backtracking loop entry, 18 

Replace top picture under mouse, 338 
Resource item descriptor, 150, 252, 334 
Close a resource file, 176 

Create a resource file, 175 

Delete a resource item from memory, 176 
Get available resource items, 177 

Open a resource file, 176 

Delete a matching clause, 78 

Delete all matching clauses, 79 

Delete a clause from a position, 78 
Reverse order of items in a list, 62 
Reverse picture list, 298 

Cursor descriptor, 334 

232, 234 

Elementary picture descriptor, 315 

Drag graphic rubber band, 340 
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save 
save_pic 
scale 
screen 
scroll menu 
sdef 

sdict 

see 

seeing 

seek 

seen 

select 
Selecting text in a window 


Selection mode of check box 


sel aill 

sel pics 
send to back 
Separators 
serconfig 
sercts 
seropen 
serstacus 
serxonxofft 
setditem 
setof 
set_gfont 
ät Link 
set_link 
set_prop 
set_tool 
Shitt pic 
shife Pires 
sign 

sin 

Size of a window 
Size of Mac display screen 
Skip 

sort 

Sound 

split 

Split line 

Spy 
spy_glass 
sqrt 
stringof 
Strings 
speckled 
square 
stripesthick 
stripesthin 
style item 
Switch 
Symbol generation 


Save interpreted programs, 80 
Save picture as a resource, 332 
Scale a picture, 256 

Find the size of display screen, 17] 
Scrolling menu selection, 131 
System relation test, 82 

System relations dictionary, 83 

Set input channel, 89 

Current input channel, 90 

Position file pointer, 104 

Close current input channel, 91 
Graphic tool program, 314 
wsitxt, 165 

151 

Select'all pictures in a window, 295 
Select pictures in a window, 294 
Send pictures to the back, 299 

l 


Configure serial channel, 114 

Set CTS handshake, 115 

Open serial channel, 113 

Get serial channel status, 115 

Set Xon/Xoff, 115 

Set the status of a dialogue item, 154 
Find ordered list of solutions, 22 
Set graphic text font, 353 

C interface link function, 191 
Pascal interface link function, 213 
Set a property value, 86 

Set current graphic tool, 319 
Translate a picture, 293 

Translate a list of pictures, 293 
Determine sign of a number, 45 

The sine of an angie in radians, 47 
wsize, 169 

screen, 17} 

Skip to a character, 97 

Sort a list, 57 

beep, 135 

Cursor descriptor, 334 

304, 310 

Set spypoints, 109 

Cursor descriptor, 334 

Square root, 43 

Atom to character list conversion, 64 
6 

Set fill pattern to speckled, 279 
Square, 239 

Set fill pattern to thick vertical stripes, 280 
Set fill pattern to thin vertical stripes, 279 
Set menu item style, 123 

Check box selection mode, 151 
gensym, 68 
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tab 

Tagged cells 

tan 

tell 

telling 

Terminal symbols 
term_expansion 
text 

text 

textbox 

text width 
thick 

thicker 

thick cross 
thin 

thinner 

ticks 

Tidying screen display 
time 

tload 

toground 
tohollow 

Tokens 

told 

Tool pane 

Tools for graphic windows 
tooi desc 

~ lace 

trans 
Transformation descriptors 
Transient pictures 
Tngonometric functions 
triple 

True 

Tuple 


U 


undo 

unify 

union _box 

unknown 

unmark_item 

up_ thumb 

User defined graphical form 
User defined syntax 


Write spaces, 97 
181 


The tangent of an angle in radians, 48 
Set output channel, 90 

oe output channel, 90 

1 

Text preprocessor, 14 

Dialogue item format descriptor, 142 
Display text, 248 

Display text in a box, 249 

Get width of atom in a font, 354 
Set pen size to 8x8 pixels, 260 
Increase size of pen, 261 

Cursor descriptor, 334 

Set pen size to 1x1 pixels, 260 
Decrease size of pen, 261 

Get system elapsed time, 112 
cleanup, 172 

Current time, 71 

Load a text file into a window, 98 
Make a hollow term ground, 31 
Make a ground term hollow, 30 
93,141 

Close current output channel, 91 
304 


314 

Get graphic tool descnption, 318 
Set tracing on, 110 

Translate a picture, 256 


2285.20 

321 

47 

Triple size of pen, 262 
True, 17 

184 


Undo last editing command, 167 
Unify with occurs check, 53 
Union of two rectangles, 358 
Action on unknown relations, 111 
Remove a menu item mark, 121 
Cursor descriptor, 334 

284 : 

160 


V 


Validation 
val_box 
val pic 
val viewer 
var 

Variable names 
varsin 
version 
Viewer 
Viewing pane 


W 


Wait 

wait click 
warning 
watch 
waves 
wohg 
wcichg 
wWErearte 
wedge 
wfont 
wfiront 
wgcreate 
whide 
white 
whitepen 
Window types 
windows 
wkill 
wpcreate 
wrename 
write 
writeqd 
wsearch 
wshow 
wsize 
wsltxt 
wsyntax 
wtype 
wvis 


X 


xrefs 


yesno 
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Validate a rectangle, 326 

Validate a picture, 327 

Validate graphic viewer, 326 

Variable test, 25 

4 

Find all variables in a term, 30 

Get current version of MacPROLOG, 69 
304, 308 

304, 311 


tices, 112 

Wait for mouse click, 343 

Warning dialogue, 133 

Cursor cescnptor, 334 

Set ful pattern to waves, 280 

Test changed flag of a window, 162 
Clear changed flag of a window, 162 
Create a display window, 159 
Filled arc, 242 

Find or set a window's font details, 170 
Move a window to the top, 168 
Create 2 graphic window, 306 

Hide a window, 167 

Set fill pattern to white, 281 

Set pen to white, 271 

159, 161, 170 

Find ail windows, 170 

Kill a window, 168 

Create a program window, 160 
Rename window, 163 

Write a term, 94 

Write a term in quoted form, 95 
Search a window, 163 

Show a window, 167 

Size and position of a window, 169 
Extract text from a window, 165 
The syntax of a window, 162 

The type of a window, 161 

Test if a window is visible, 168 


Program's external references, 81 


Ask a yes/no question, 129 
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Transfer of the Software Package and End-User Licence 
In accordance with the terms of the End-User Licensing Agreement granted by LPA to the 
original purchaser of the MacPROLOG 2.0 Software Package, the owner (either the onginal 
purchaser or a person to whom the Package and End-User Licensing Agreement have been 
transfered in accordance with the Agreement) may transfer the whole of the Package and the 
single-computer licence provided that the owner and the transferee both sign this 
re-registration form and agreement and return it within twenty-eight days to 

Logic Programming Associates Ltd 

Smdio 4 

The Royal Victoria Patriotic Building 

Trinity Road 

LONDON SW18 3SX 


Please note that any offers which LPA may make of updates at special 
rates are available only to the Registered Owners. 


5 oi . o 


Agreement between the Owner and Transferee and Logic Programming Associates Limited 


. (LPA) 

1 The Owner transfers to the Transferee the whole of the Package and all copies, 
updates and modifications to it (other than which have already been destroyed by the 
Owner) together with the Owner's licence to use the Package on a single-computer. 


2. The Transferee agrees with LPA to accept all the terms and conditions of the 
End-User Licence granted to the original purchaser. 


3: Both the Owner and the Transferee warrant to LPA that there ts attached to every 
copy and modification of the Software a permanent label giving the name of the 
Software and stating that it is the property of LPA. 

Signed by the Owner: 


Name (please Pint) cevccconsosaceessccdccnsesnscenccrcsnssnssrdctuadsanascsensecssrsccesacssevescoreanosssanvsseess 


Address (please print) .........c-ssccsrscnscssrssssscsscrnececesensenenenasesensensbenesaasansseasnacasoescasasnars 


ee we ECE OS OR SH ESHER HHA SEES PHOEBE TEESE EOCSOHEHFIH HE EEEPSCSOESOCESATESEH HESS ESSE EHS EHSSAHSETSROSSOROEHOSCHTOCSCOREP EH ESHEeEesEe eee ae 


POOF Oa ewe HERETO ESE ARETE OPES EET RSET HE EEAOT ORE REE HEED HATA ESSESEHFA EE SEF EERE E BEES HAASE ASHE SHAE E TET EE HATZ awa eT TES 


Signed by the Transferee: 
Name (please print) ......cccsssecccssseecceseesrecstersecsenrerresassassscesorsnacssvsseeescennvansccaranseeea ns 


Address (please print) .......cccccsssscsssssscetssreneserorecensenreessacaeaas season seasons sneneecessseesnsenecaes 


woe POORER EES ESSA EH ER ESSER SAAS OEOT FEF ESHSHOSOESEREEEESEHESORSETEV USES TASER HaLaeLOReEFTETEvATESGETENENssEaeaLALAs HH EAH AES BAEeE 


eee ee aR READE REO HARE SEEEET RE SAO E TEESE EERE RAEH OEE FETE SRE H ASHE EESETH ESOS HS HESS GE EHEHEEEE ERASER DEST SESS RT TES TST ET TUT EES 


~ -— —— ee oe 


